Add left navigation bar on github pages with .md files

Question

I want to create some documentation for our project in GitHub.

I can see, that GitHub already provides these options with GitHub pages. In the intro video, I can see that you can and multiple pages (.md files) and navigation.

I already add Jekyll.

But:

• I can't find how to add a left navigation bar
• how to organise files so that it will know where to find other pages

Right now I have

-> Root
  |
  -> _config.yml
  -> about.md
  -> index.md
  -> README.md
  -> docs
     |
     -> first_page.md
     -> second_page.md

The config file I have

title: title
description: YOUR DESCRIPTION
baseurl: 'our_domain'
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge
plugins:
  - jekyll-default-layout

# Navigation
# List links that should appear in the site sidebar here
navigation:
  - text: Documentation
    internal: true
    url: ./docs

Answer 1

The just the docs theme mentioned by Benjamin includes a sidebar in the default layout using {% include components/sidebar.html %} This sidebar.html is very interesting but a quite complex example on how to do it, including other files, etc.

In short:

1. Adjust your layout.
2. Loop over some kind of data file, or in your case site.navigation
3. Use the returned information (text, internal, url) and include it in your sidebar.

Very simple example:

<nav>
  <ul>
    {% for item in site.navigation %}
      <li>
        <a href="{{ item.url }}">{{ item.text }}</a>
      </li>
    {% endfor %}
  </ul>
</nav>

The Jekyll docs include simpler examples on how to loop such files. The docs also explain how to use a YAML file in the _data folder for this instead.