Styleguide

Installation Guidelines Colors Icons Layout Grid

Components

Buttons Button Groups Tooltips Forms Tables Navigation Tabs Blankslate Dropdowns List Groups Filter Lists Panels Labels Modal Spinner Switch Pagination Alerts Labels Badges Markdown

What is it?

GitBook Styleguide is a collection of styling, components and rules; which are being used by the GitBook team on our official websites such as gitbook.com.

This styleguide is open to criticsms and feedback, feel free to post an issue on GitHub.

Installation

GitBook styleguide can be installed using NPM, the module is published as gitbook-styleguide, current version is 5.7.0.

$ npm install gitbook-styleguide@5.7.0

Simply include node_modules/gitbook-styleguide/less/main.less in your less file.

Contents of folder node_modules/gitbook-styleguide/assets should be accessible from the web server. The root folder can be set using the less variable @gb-assets-path.

Guidelines

HTML5 doctype

It makes use of certain HTML elements and CSS properties that require the use of the HTML5 doctype. Include it at the beginning of all your pages.

<!DOCTYPE html>
<html lang="en">
  ...
</html>

Box-sizing

We reset box-sizing to border-box for every element. This allows us to more easily assign widths to elements that also have padding and borders.

Less Variables

Format

Variables should use dash instead of uppercases. For example @gb-hello-world is valid, but @gb-helloWorld is not.

Prefix

All variables defined by this module should be prefixed by @gb-.

Paths

Variables that defined a path should not finish with a slash. For example @gb-static-folder: "/static" is valid.

Page Layout

<!DOCTYPE html>
<html lang="en">
    ...
    <body>
        <div class="gb-page-wrapper">
            <div class="gb-page-header">

            </div>
            <div class="gb-page-body">

            </div>
            <div class="gb-page-footer">

            </div>
        </div>
    </body>
</html>

Grid System

Grid systems are used for creating page layouts through a series of rows and columns that house your content.

  • There are 12 columns per row
  • Rows must be placed within a .container
  • Use .row to create horizontal groups of columns.
  • Content should be placed within columns, and only columns may be immediate children of rows.
.col-md-8
.col-md-4
<div class="row">
    <div class="col-md-8">.col-md-8</div>
    <div class="col-md-4">.col-md-4</div>
</div>
.col-md-4
.col-md-4
.col-md-4
<div class="row">
    <div class="col-md-4">.col-md-4</div>
    <div class="col-md-4">.col-md-4</div>
    <div class="col-md-4">.col-md-4</div>
</div>
.col-md-6
.col-md-6
<div class="row">
    <div class="col-md-6">.col-md-6</div>
    <div class="col-md-6">.col-md-6</div>
</div>

Offsetting columns

Move columns to the right using .col-md-offset-* classes. These classes increase the left margin of a column by * columns. For example, .col-md-offset-4 moves .col-md-4 over four columns.

.col-md-4
.col-md-4 .col-md-offset-4
.col-md-3 .col-md-offset-3
.col-md-3 .col-md-offset-3
.col-md-6 .col-md-offset-3
<div class="row">
    <div class="col-md-4">.col-md-4</div>
    <div class="col-md-4 col-md-offset-4">.col-md-4 .col-md-offset-4</div>
</div>
<div class="row">
    <div class="col-md-3 col-md-offset-3">.col-md-3 .col-md-offset-3</div>
    <div class="col-md-3 col-md-offset-3">.col-md-3 .col-md-offset-3</div>
</div>
<div class="row">
    <div class="col-md-6 col-md-offset-3">.col-md-6 .col-md-offset-3</div>
</div>

Utilities

For faster mobile-friendly development, use these utility classes for showing and hiding content by device via media query. Also included are utility classes for toggling content when printed.

  Extra small devices(<768px) Small devices (≥768px) Medium devices (≥992px) Large devices (≥1200px)
.hidden Hidden Hidden Hidden Hidden
.hidden-xs Hidden Visible Visible Visible
.hidden-sm Visible Hidden Visible Visible
.hidden-md Visible Visible Hidden Visible
.hidden-lg Visible Visible Visible Hidden

Colors

Color palettes is accessible throught less variables:

@gb-palette-black
@gb-palette-gray-light
@gb-palette-gray
@gb-palette-gray-outline
@gb-palette-gray-dark
@gb-palette-gray-darker
@gb-palette-darkgray
@gb-palette-blue / @gb-brand-primary
@gb-palette-green / @gb-brand-success
@gb-palette-clearblue / @gb-brand-info
@gb-palette-orange / @gb-brand-warning
@gb-palette-red / @gb-brand-danger

Icons

Icons from octicons are used for GitBook. You should use <i> tags for icons.

<i class="octicon octicon-book"></i>

Buttons

Buttons are used for actions, like in forms, while textual hyperlinks are used for destinations, or moving from one page to another.

Default buttons

Use the standard—yet classy—.btn for form actions and primary page actions. These are used extensively around the site.

When using a <button> element, always specify a type. When using a <a> element, always add role="button" for accessibility.

Link button
<button class="btn" type="button">Button button</button>
<a class="btn" href="#" role="button">Link button</a>

Sizes

Buttons are availables in multiples sizes: Large, Normal, Small and Extra-Small.

<button class="btn btn-lg" type="button">Large Button</button>
<button class="btn" type="button">Button</button>
<button class="btn btn-sm" type="button">Small button</button>
<button class="btn btn-xs" type="button">Extra Small button</button>

Styles

Buttons can be filled to indicate a more important action:

<button class="btn btn-primary" type="button">Primary button</button>
<button class="btn btn-success" type="button">Success button</button>
<button class="btn btn-danger" type="button">Danger button</button>
<button class="btn btn-warning" type="button">Warning button</button>

Colored Text

Different styles of buttons are available to indicate different kind of actions.

<button class="btn btn-text-primary" type="button">Primary button</button>
<button class="btn btn-text-success" type="button">Success button</button>
<button class="btn btn-text-danger" type="button">Danger button</button>
<button class="btn btn-text-warning" type="button">Warning button</button>
<button class="btn btn-link" type="button">Link button</button>
<button class="btn btn-text-link" type="button">Text Link button</button>

Block Buttons

Create block level buttons—those that span the full width of a parent— by adding .btn-block.

<button type="button" class="btn btn-primary btn-lg btn-block">Block level button</button>
<button type="button" class="btn btn-lg btn-block">Block level button</button>

Outline

Outline buttons downplay an action as they appear like boxy links. Just add .btn-outline and go.

<button class="btn btn-count" type="button">Default button</button>
<button class="btn btn-primary btn-outline" type="button">Primary button</button>
<button class="btn btn-success btn-outline" type="button">Success button</button>
<button class="btn btn-danger btn-outline" type="button">Danger button</button>
<button class="btn btn-warning btn-outline" type="button">Warning button</button>

Plain

Plain buttons are flat and filled buttons.

<button class="btn btn-plain" type="button">Default button</button>
<button class="btn btn-primary btn-plain" type="button">Primary button</button>
<button class="btn btn-success btn-plain" type="button">Success button</button>
<button class="btn btn-danger btn-plain" type="button">Danger button</button>
<button class="btn btn-warning btn-plain" type="button">Warning button</button>

States

Buttons can have different states:

<div class="btn-toolbar">
    <button class="btn" type="button">Default</button>
    <button class="btn active" type="button">:active or .active</button>
    <button class="btn" disabled type="button">:disabled or .disabled</button>
</div>
<div class="btn-toolbar">
    <button class="btn btn-primary" type="button">Default</button>
    <button class="btn btn-primary active" type="button">:active or .active</button>
    <button class="btn btn-primary" disabled type="button">:disabled or .disabled</button>
</div>

Buttons Labels

Buttons can contains a new-line label:

<button class="btn btn-primary btn-block" type="button">
    Download for OS X
    <span class="btn-label">OS X 10.9 or later</span>
</button>

Button Groups

Button groups and toolbars are used to group actions together.

Link button 
<div class="btn-group">
    <button class="btn" type="button">Button button</button>
    <a class="btn" href="#" role="button">Link button</a>
</div>

Toolbars can contain multiple group of buttons:

Link button
Success button
0 
<div class="btn-toolbar">
    <div class="btn-group">
        <button class="btn" type="button">Button button</button>
        <a class="btn" href="#" role="button">Link button</a>
    </div>
    <div class="btn-group">
        <button class="btn btn-danger" type="button">Danger button</button>
        <a class="btn btn-success" href="#" role="button">Success button</a>
    </div>
    <div class="btn-group">
        <button class="btn" type="button">Star</button>
        <a class="btn btn-count" href="#" role="button">0</a>
    </div>
</div>

Button groups can be justified, to make a group of buttons stretch at equal sizes to span the entire width of its parent. Also works with button dropdowns within the button group.

Button 1 Button 2 
<div class="btn-group btn-group-justified">
    <a class="btn" href="#" role="button">Button 1</a>
    <a class="btn" href="#" role="button">Button 2</a>
</div>

Tooltips

Add tooltips built entirely in CSS to nearly any element. Just add a few classes and an aria-label attribute.

Remember, aria-label and tooltip classes must go directly on <button> and <a> elements. Tooltip classes also conflict with icon classes, and as such, must go on a parent element instead of the icon.

<button class="btn tooltipped tooltipped-nw tooltipped-o" aria-label="Top, left" type="button">.tooltipped-nw</button>
<button class="btn tooltipped tooltipped-w tooltipped-o" aria-label="Bottom, left" type="button">.tooltipped-w</button>
<button class="btn tooltipped tooltipped-ne tooltipped-o" aria-label="Top, right" type="button">.tooltipped-ne</button>
<button class="btn tooltipped tooltipped-o" aria-label="Bottom, center (default)" type="button">Button</button>

Forms

Example block-level help text here.

<form>
    <div class="form-group">
        <label for="exampleInputEmail1">Email address</label>
        <input type="email" class="form-control" id="exampleInputEmail1" placeholder="Enter email">
    </div>
    <div class="form-group">
        <label for="exampleInputPassword1">Password</label>
        <input type="password" class="form-control" id="exampleInputPassword1" placeholder="Password">
    </div>
    <div class="form-group">
        <label for="exampleInputSelect">Type <span class="note">(Optional)</span></label>
        <select class="form-control" id="exampleInputSelect">
            <option>User</option>
            <option>Organization</option>
        </select>
    </div>
    <div class="form-group">
        <label for="exampleInputFile">File input</label>
        <input type="file" id="exampleInputFile">
        <p class="help-block">Example block-level help text here.</p>
    </div>
    <div class="checkbox">
        <label>
            <input type="checkbox"> Check me out
        </label>
    </div>
    <button type="submit" class="btn">Submit</button>
</form>

Input can have different states:

<div class="form-group">
    <input type="text" class="form-control" value="Normal state">
</div>
<div class="form-group">
    <input type="text" class="form-control" disabled value="Disabled state">
</div>
<div class="form-group">
    <input type="text" class="form-control focus" value="Focus state">
</div>
<div class="form-group has-error">
    <input type="text" class="form-control focus" value="Error state">
</div>

And different sizes

<div class="form-group">
    <input type="text" class="form-control input-lg" placeholder=".form-control.input-lg">
</div>
<div class="form-group">
    <input type="text" class="form-control" placeholder=".form-control">
</div>
<div class="form-group">
    <input type="text" class="form-control input-sm" placeholder=".form-control.input-sm">
</div>
<div class="form-group">
    <input type="text" class="form-control input-xs" placeholder=".form-control.input-xs">
</div>

Extend form controls by adding text or buttons before, after, or on both sides of any text-based <input>. Use .input-group with an .input-group-addon to prepend or append elements to a single .form-control.

@
@example.com
$ .00
I confirm, I want to delete 
<div class="form-group">
    <div class="input-group">
        <span class="input-group-addon" id="basic-addon1">@</span>
        <input type="text" class="form-control" placeholder="Username" aria-describedby="basic-addon1">
    </div>
</div>
<div class="form-group">
    <div class="input-group">
        <input type="text" class="form-control" placeholder="Recipient's username" aria-describedby="basic-addon2">
        <span class="input-group-addon" id="basic-addon2">@example.com</span>
    </div>
</div>
<div class="form-group">
    <div class="input-group">
        <span class="input-group-addon">$</span>
        <input type="text" class="form-control" aria-label="Amount (to the nearest dollar)">
        <span class="input-group-addon">.00</span>
    </div>
</div>
<div class="form-group">
    <div class="input-group">
        <span class="input-group-addon">
            <input type="checkbox"> I confirm, I want to delete
        </span>
        <input type="text" class="form-control" placeholder="Please type in the username.">
        <span class="input-group-btn">
            <button class="btn" type="submit">Delete</button>
        </span>
    </div>
</div>

Tables

Optional table caption.
# First Name Last Name Username
1 Mark Otto @mdo
2 Jacob Thornton @fat 
<table class="table">
    <caption>Optional table caption.</caption>
    <thead>
        <tr>
            <th>#</th>
            <th>First Name</th>
            <th>Last Name</th>
            <th>Username</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <th scope="row">1</th>
            <td>Mark</td>
            <td>Otto</td>
            <td>@mdo</td>
        </tr>
        <tr>
            <th scope="row">2</th>
            <td>Jacob</td>
            <td>Thornton</td>
            <td>@fat</td>
        </tr>
    </tbody>
</table>

Navigation

.pagehead can be used to display a horrizontal navigation bar:

Explore GitBook

<div class="pagehead">
    <div class="container">
        <h1>Explore GitBook</h1>

        <form class="search-bar hidden-xs hidden-sm pull-right" method="get" action="/search">
            <i class="octicon octicon-search"></i><input type="text" name="q" value="" class="form-control" placeholder="Search Books">
        </form>
    </div>
</div>

Tabs

...
...
<div class="tabs">
    <ul class="tabs-nav">
        <li>
            <a href="#github" data-toggle="tab">My Books</a>
        </li>
        <li class="active">
            <a href="#followers" data-toggle="tab">Followers</a>
        </li>
    </ul>
    <div class="tabs-content">
        <div class="tab-pane" id="books">...</div>
        <div class="tab-pane active" id="followers">...</div>
    </div>
</div>

Justified navigation:

<div class="tabs">
    <ul class="tabs-nav justified">
        <li>
            <a href="#github" data-toggle="tab">My Books</a>
        </li>
        <li class="active">
            <a href="#followers" data-toggle="tab">Followers</a>
        </li>
    </ul>
</div>

Blankslate

Blankslates are for when there is a lack of content within a page or section. Use them as placeholders to tell users why something isn’t there. Be sure to provide an action to add content as well.

Basic example

Wrap some content in the outer .blankslate wrapper to give it the blankslate appearance.

This is a blank slate

Use it to provide information when no dynamic content exists.

<div class="blankslate">
    <div class="icon"><i class="octicon octicon-book"></i></div>
    <h3>This is a blank slate</h3>
    <p>Use it to provide information when no dynamic content exists.</p>
</div>

With some background

This is a blank slate

Use it to provide information when no dynamic content exists.

<div class="blankslate with-background">
    <div class="icon"><i class="octicon octicon-book"></i></div>
    <h3>This is a blank slate</h3>
    <p>Use it to provide information when no dynamic content exists.</p>
</div>

Full width

Container will occupy the entire available width.

This is a blank slate

Use it to provide information when no dynamic content exists.

<div class="blankslate with-background full-width">
    <div class="icon"><i class="octicon octicon-book"></i></div>
    <h3>This is a blank slate</h3>
    <p>Use it to provide information when no dynamic content exists.</p>
</div>

Dropdowns

Dropdown menu can be added to .btn-group.

<div class="btn-group dropdown">
    <button class="btn" type="button">Toggle Dropdown <span class="dropdown-caret"></span></button>
    <ul class="dropdown-menu open">
        <li class="dropdown-header">This is an header</li>
        <li><a href="#">Entry 1</a></li>
        <li class="active">
            <a href="#">Entry 2 (active)</a>
            <ul class="dropdown-menu open">
                <li>
                    <a href="#">Entry 2.1 (hover me)</a>
                    <ul class="dropdown-menu">
                        <li class="disabled"><a href="#">Entry 2.1.1</a></li>
                        <li><a href="#">Entry 2.1.2</a></li>
                    </ul>
                </li>
                <li><a href="#">Entry 2.2</a></li>
            </ul>
        </li>
        <li><a href="#">Entry 3</a></li>
    </ul>
</div>

.pull-right and .pull-left classes can be used to change the direction of the dropdown:

<div class="btn-group pull-left dropdown">
    <button class="btn" type="button">Left</button>
    <ul class="dropdown-menu open">
        <li><a href="#">This is a long entry</a></li>
    </ul>
</div>
<div class="btn-group pull-right dropdown">
    <button class="btn" type="button">Right</button>
    <ul class="dropdown-menu open">
        <li><a href="#">This is a long entry <span class="help-label">Help Text</span></a></li>
    </ul>
</div>

List Groups

Item 1 Item 2 Item 3 
<div class="list-group">
    <a href="#" class="list-group-item">Item 1</a>
    <a href="#" class="list-group-item active">Item 2</a>
    <a href="#" class="list-group-item">Item 3</a>
</div>

Icons, badges and images can also be added to list items:

Image Icon on the left Icon on the right 10 Badge 
<div class="list-group">
    <a href="#" class="list-group-item"><img class="list-image" src="https://avatars2.githubusercontent.com/u/845425?v=3&s=460" /> Image</a>
    <a href="#" class="list-group-item active"><i class="octicon octicon-book"></i> Icon on the left</a>
    <a href="#" class="list-group-item"><i class="octicon octicon-book pull-right"></i> Icon on the right</a>
    <a href="#" class="list-group-item"><span class="badge">10</span> Badge</a>
</div>

Filter List

A vertical list of filters.

<ul class="filter-list">
  <li>
    <a href="#" class="filter-item selected">
      <span class="count">21</span>
      First filter
    </a>
  </li>
  <li>
    <a href="#" class="filter-item">
      <span class="count">3</span>
      Second filter
    </a>
  </li>
  <li>
    <a href="#" class="filter-item">
      Third filter
    </a>
  </li>
</ul>

Panels

Title

Body of the panel
Optional footer of the panel 
<div class="panel panel-default">
    <div class="panel-heading">
        <h3 class="panel-title">Title</h3>
    </div>
    <div class="panel-body">
        Body of the panel
    </div>
    <div class="panel-footer">
        Optional footer of the panel
    </div>
</div>

Panels can also include a .list-group.

Title

Item 1 Item 2 Item 3 
<div class="panel panel-default">
    <div class="panel-heading">
        <h3 class="panel-title">Title</h3>
    </div>
    <div class="list-group">
        <a href="#" class="list-group-item">Item 1</a>
        <a href="#" class="list-group-item active">Item 2</a>
        <a href="#" class="list-group-item">Item 3</a>
    </div>
</div>

And have different styles:

Title

Body of the panel

Title

Body of the panel

Title

Body of the panel

Title

Body of the panel 
<div class="panel panel-danger">
    <div class="panel-heading">
        <h3 class="panel-title">Title</h3>
    </div>
    <div class="panel-body">
        Body of the panel
    </div>
</div>
<div class="panel panel-warning">
    <div class="panel-heading">
        <h3 class="panel-title">Title</h3>
    </div>
    <div class="panel-body">
        Body of the panel
    </div>
</div>
<div class="panel panel-success">
    <div class="panel-heading">
        <h3 class="panel-title">Title</h3>
    </div>
    <div class="panel-body">
        Body of the panel
    </div>
</div>
<div class="panel panel-info">
    <div class="panel-heading">
        <h3 class="panel-title">Title</h3>
    </div>
    <div class="panel-body">
        Body of the panel
    </div>
</div>

Include a table in a panel:

Title
Body
# Title ID Updated
1 PHP php 1 month ago
2 Javascript js 1 month ago 
<div class="panel panel-default">
    <div class="panel-heading">
        <b>Title</b>
    </div>
    <div class="panel-body">
        Body
    </div>
    <table class="table">
        <thead>
            <tr>
                <th>#</th>
                <th>Title</th>
                <th>ID</th>
                <th>Updated</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <th scope="row">1</th>
                <td>PHP</td>
                <td>php</td>
                <td>1 month ago</td>
            </tr>
            <tr>
                <th scope="row">2</th>
                <td>Javascript</td>
                <td>js</td>
                <td>1 month ago</td>
            </tr>
        </tbody>
    </table>
</div>

Modals

Modal (.modal) can be used in 3 sizes: medium (default), small (.modal-sm) and large (.modal-lg). .modal-backdrop can be use to set a fixed backdrop for modals.

Title

×
Body of the modal 
<div class="modal">
    <div class="modal-heading">
        <h4>Title</h4>
        <a href="#" class="modal-close">&times;</a>
    </div>
    <div class="modal-body">
        Body of the modal
    </div>
    <div class="modal-footer">
        <button class="btn">Close</button>
    </div>
</div>

Spinner

Spinner can be use to indicate a loading operation.

<div class="gb-spinner spinner-sm"></div>
<div class="gb-spinner"></div>
<div class="gb-spinner spinner-lg"></div>
<div class="gb-spinner spinner-centered"></div>

Switch

Switch can replace checkbox (without JavaScript):

<div class="checkbox checkbox-switch">
    <label>
        <input type="checkbox">
        <span></span>
        Better checkbox
    </label>
</div>
<div class="checkbox checkbox-switch switch-right">
    <label>
        <input type="checkbox" checked>
        <span></span>
        Switch on the right
    </label>
</div>
<div class="checkbox checkbox-switch switch-xs">
    <label>
        <input type="checkbox" checked>
        <span></span>
        Small switch
    </label>
</div>
<div class="checkbox checkbox-switch switch-lg">
    <label>
        <input type="checkbox" checked>
        <span></span>
        Big switch
    </label>
</div>
<div class="checkbox checkbox-switch">
    <label>
        <input type="checkbox" disabled>
        <span></span>
        Disabled checkbox
    </label>
</div>

Pagination

<div class="pagination">
    <ul class="pagination-pages">
        <li class="active"><a href="?page=0">0</a></li>
        <li><a href="?page=1">1</a></li>
        <li><a href="?page=2">2</a></li>
        <li><span class="separator">...</span></li>
        <li><a href="?page=3">3</a></li>
    </ul>
    <ul class="pagination-nav">
        <li><a href="?page=1">next page »</a></li>
    </ul>
</div>

Alerts

This is an alert! Details 
<div class="alert alert-danger">
    This is an alert!

    <a href="#" class="alert-btn">Details <i class="octicon octicon-chevron-right"></i></a>
</div>
This is an alert! 
<div class="alert alert-success">
    This is an alert!

    <a href="#" class="alert-btn"><i class="octicon octicon-x"></i></a>
</div>
This is an alert! 
<div class="alert alert-info">
    This is an alert!
</div>
This is an alert! 
<div class="alert alert-warning">
    This is an alert!
</div>

Labels

Warning Label Warning !

Danger Label Danger !

Success Label Success !

Info Label Info !

<h1>Warning Label <span class="label label-warning">Warning !</span></h1>
<h1>Danger Label <span class="label label-danger">Danger !</span></h1>
<h1>Success Label <span class="label label-success">Success !</span></h1>
<h1>Info Label <span class="label label-info">Info !</span></h1>

Badges

<button class="btn" type="button">
    Default <span class="badge">10</span>
</button>
<button class="btn" type="button">
    Warning <span class="badge badge-warning">10</span>
</button>
<button class="btn" type="button">
    Danger <span class="badge badge-danger">10</span>
</button>
<button class="btn" type="button">
    Success <span class="badge badge-success">10</span>
</button>
<button class="btn" type="button">
    Info <span class="badge badge-info">10</span>
</button>

Markdown

HTML from Markdown following GitHub Flavored Markdown syntax can be styled easily using .gb-markdown.

Heading 1

Heading 2

Heading 3

Heading 4

<div class="gb-markdown">
    <h1>Heading 1</h1>
    <h2>Heading 2</h2>
    <h3>Heading 3</h3>
    <h4>Heading 4</h4>
</div>