index.html

---
layout: default
title: Home
description: Simple documentation template for Github pages
isHome: true
---

<section class="bs-docs-section">
  <h1 id="overview" class="page-header">Overview</h1>

  <blockquote>
    This is a Jekyll template I use for my GitHub projects documentations. It is heavily based on official Bootstrap
    documentation and is designed to be quickly deployed.
  </blockquote>

  <h3 id="features">Features</h3>

  <ul>
    <li>Responsive Bootstrap theme</li>
    <li>Automatic syntax highlight</li>
    <li>Multi-page</li>
    <li>Automatic menu</li>
    <li>Automatic heading anchors</li>
    <li>Configurable additional links</li>
    <li>Github counters</li>
    <li>Twitter &amp; Facebook buttons</li>
    <li>Download options popup</li>
    <li>Changelog page generated from GitHub releases</li>
  </ul>

  <h3 id="examples">Examples</h3>

  <ul>
    <li><a href="http://photo-sphere-viewer.js.org">Photo Sphere Viewer</a></li>
    <li><a href="http://querybuilder.js.org">jQuery QueryBuilder</a></li>
    <li><a href="http://bootstrap-confirmation.js.org">Bootstrap Confirmation</a></li>
    <li><a href="http://mistic100.github.io/angular-smilies">AngularJS Smilies</a></li>
  </ul>
</section>


<section class="bs-docs-section">
  <h1 id="installation" class="page-header">Installation</h1>

  <h2 id="install-jekyll">Install Jekyll</h2>
  <p>
    Follow the <a href="https://help.github.com/articles/using-jekyll-with-pages">GitHub guide</a> to install Jekyll
    on your computer. The big steps are:
  </p>

<!-- @formatter:off -->
{% highlight bash %}
$ apt-get install ruby ruby-dev
$ gem install bundler
$ git clone git://github.com/mistic100/jekyll-bootstrap-doc
$ bundle install
$ bundle exec jekyll serve
{% endhighlight %}
<!-- @formatter:on -->

  <h2 id="configuration">Configuration</h2>
  <p>Adapt the <code>_config.yml</code> file to your project.</p>

  <div class="table-responsive">
    <table class="table table-bordered table-striped">
      <thead>
        <tr>
          <th style="width: 130px;">Name</th>
          <th>description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>name</td>
          <td>Name of the project.</td>
        </tr>
        <tr>
          <td>version</td>
          <td>Current version of the project</td>
        </tr>
        <tr>
          <td>license</td>
          <td>License of the project</td>
        </tr>
        <tr>
          <td>licenseUrl</td>
          <td>URL of the license text</td>
        </tr>
        <tr>
          <td>favicon</td>
          <td>Extension of the favicon</td>
        </tr>
        <tr>
          <td>download</td>
          <td>Configuration of the download button (see comment in the file)</td>
        </tr>
        <tr>
          <td>headerLinks</td>
          <td>
            List of links to display on the right of the top menu. Each item must contain
            <code>title</code> and <code>url</code> keys
          </td>
        </tr>
        <tr>
          <td>footerLinks</td>
          <td>
            List of links to display on the bottom of the page. Each item must contain
            <code>title</code> and <code>url</code> keys
          </td>
        </tr>
        <tr>
          <td>header</td>
          <td>
            Configuration of the header, two colors gradient and boolean to activate or deactivate
            <a href="http://qrohlf.com/trianglify/">Trianglify</a> generator
          </td>
        </tr>
        <tr>
          <td>analytics</td>
          <td>
            Google analytics identifiers. Provide <code>account</code> and <code>domain</code> or leave empty to
            deactivate
          </td>
        </tr>
      </tbody>
    </table>
  </div>

  <h3 id="social-buttons" data-no-menu>Social buttons</h3>
  <div class="table-responsive">
    <table class="table table-bordered table-striped">
      <thead>
        <tr>
          <th style="width: 130px;">Name</th>
          <th>description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>githubButton</td>
          <td>
            Data used to generate <a href="http://ghbtns.com/">GitHub Buttons</a>.
            Provide <code>user</code> and <code>repo</code>
          </td>
        </tr>
        <tr>
          <td>twitter.enabled</td>
          <td>Enable or disable Twitter "Tweet" button</td>
        </tr>
        <tr>
          <td>twitter.via</td>
          <td>Account linked to "Tweet" button</td>
        </tr>
        <tr>
          <td>twitter.hash</td>
          <td>Default hashtags for the "Tweet" button</td>
        </tr>
        <tr>
          <td>twitter.account</td>
          <td>Account for Twitter "Follow" button. Leave empty to deactivate</td>
        </tr>
        <tr>
          <td>facebook.enabled</td>
          <td>Enable or disable Facebook "Like" &amp; "Share" buttons</td>
        </tr>
        <tr>
          <td>facebook.profileUrl</td>
          <td>Profile for Facebook "Follow" button. Leave empty to deactivate</td>
        </tr>
      </tbody>
    </table>
  </div>
</section>


<section class="bs-docs-section">
  <h1 id="usage" class="page-header">Usage</h1>

  <h2 id="pages">Pages</h2>
  <p>
    The main page is the <code>index.html</code> file. You can also add additional pages by creating <code>.html</code>
    files in the root folder or in any sub-folder. Each page file must begins with a template declaration:
  </p>

<!-- @formatter:off -->
{% highlight html %}
---
layout: default
title: Home
description: Simple documentation template for Github pages
---

<!-- content -->
{% endhighlight %}
<!-- @formatter:on -->

  <p>
    Set <code>isHome</code> to <code>true</code> on the main page file, the homepage will have a bigger header with a
    central download button.
  </p>

<!-- @formatter:off -->
{% highlight html %}
---
..........
isHome: true
---
{% endhighlight %}
<!-- @formatter:on -->

  <p>
    Set <code>hide</code> to <code>true</code> to hide a page from the main menu, the page will still be accessible
    with direct link. <a href="hidden.html">Example</a>.
  </p>

<!-- @formatter:off -->
{% highlight html %}
---
..........
hide: true
---
{% endhighlight %}
<!-- @formatter:on -->

  <h2 id="titles">Titles</h2>
  <p>In order to get the right menu automatically generated you must respect some conventions.</p>

<!-- @formatter:off -->
{% highlight html %}
<!-- wrap each main section with "bs-docs-section" class -->
<section class="bs-docs-section">
  <!-- each section must contain ONE h1 with an id and optionally a "page-header" class -->
  <h1 id="first-level" class="page-header">First level</h1>

  <!-- you can optionally declare sub-sections with h2/h3 with an id -->
  <h2 id="sub-section">Second level</h2>

  <h3 id="another-sub-section">Still second level</h3>
</section>
{% endhighlight %}
<!-- @formatter:on -->

  <p>
    If you want an <code>&lt;h1-3&gt;</code> with an <code>id</code> but not visible in the menu, add a
    <code>data-no-menu</code> attribute to it.
  </p>

  <!-- @formatter:off -->
{% highlight html %}
<h2 id="my-id" data-no-menu>Title</h2>
{% endhighlight %}
<!-- @formatter:on -->

  <h2 id="anchors">Anchors</h2>
  <p>
    A paragraph (§) link is added next to every <code>&lt;h1-5&gt;</code> with an <code>id</code> attribute in order
    to easily right-click and copy the link to a particular section. The link is visible when hovering the title.
  </p>

  <h2 id="highlight">Syntax highlight</h2>
  <p>
    The powerful Pygments highlighter is activated on the template, just wrap your unescaped source code with the
    <code>{{ "{% highlight ... " }}%}</code> directive.
  </p>

<!-- @formatter:off -->
{% highlight text %}
{{ "{% highlight html " }}%}
<div>Some <b>HTML</b></div>
{{ "{% endhighlight " }}%}

{{ "{% highlight javascript " }}%}
alert('Some javascript');
{{ "{% endhighlight " }}%}
{% endhighlight %}
<!-- @formatter:on -->

  <h2 id="resources">Resources &amp; links</h2>
  <p>
    If you need to create internal links between your pages, or include resources (JS &amp; CSS), always start your
    URLs with <code>{{ "{{site.github.url" }}}}</code>.
  </p>

  <!-- @formatter:off -->
{% highlight html %}
<script src="{{ "{{site.github.url" }}}}/dist/my-script.js"></script>

<a href="{{ "{{site.github.url" }}}}/about/index.html">About</a>
{% endhighlight %}
<!-- @formatter:on -->

  <h2 id="bootbox">Bootbox</h2>
  <p>
    <a href="http://bootboxjs.com/">Bootbox</a> is installed with a syntax sugar to easily create pop-in content.
    To use this sugar you must create a clickable element with a <code>data-bootbox</code> attribute and an hidden
    content holder with a corresponding <code>id</code> attribute.
  </p>

  <!-- @formatter:off -->
{% highlight html %}
<button class="btn btn-primary btn-xs" data-bootbox="my-content">Button title</button>

<div id="my-content" class="hidden" title="Pop-in title">
  Pop-in content
</div>
{% endhighlight %}
  <!-- @formatter:on -->

  <h2 id="gems">Plugins</h2>
  <p>
    All available Jekyll plugins are installed by default, you can remove them by modifying the <code>gems</code>
    parameter in <code>_config.yml</code>. See the documentation on
    <a href="https://help.github.com/articles/using-jekyll-plugins-with-github-pages/">GitHub Help</a> pages.
  </p>

  <h2 id="bower">Bower</h2>
  <p>
    Feel free to use the <code>bower.json</code> to manage your front dependencies. Bower packages are added the
    <code>dist</code> directory and <b>MUST</b> be pushed to the repository. jQuery and Bootstrap are ignored by
    <code>.gitignore</code> as already loaded from a CDN.
  </p>

</section>