I have just added the company handbooks to our Jekyll-powered website at Next. We used Markdown to write the content of the handbooks so that anyone in the company would be able to update them.
The blog was recently moved from Tumblr to Jekyll and Markdown has proven to be popular at Next. To get the handbooks on our website up and running, I first created static HTML versions of them. The aim was to then have each handbook as a Markdown file, including the table of contents for each chapter. This would allow you to not only edit existing chapters, but to add new ones in future.
The markup for the anchors of the table of contents requires the ID of an HTML element plus a label. This data lends itself to a block mapping in YAML Front Matter, which is a collection of key: value pairs. After a quick Google search, I found out how to achieve this in Jekyll on Stack Overflow (as is so often the case).
Below is a sample of the YAML Front Matter in one of the handbooks:
chapters:
welcome: "Welcome"
your-first-day: "Your First Day"And the code to generate the table of contents in the layout:
<ol class="list">
{% for chapter in page.chapters %}
<li><a href="#{{ chapter[0] }}">{{ chapter[1] }}</a></li>
{% endfor %}
</ol>In the code sample above chapter[0] gets the key and chapter[1] the value of the pair, i.e. #welcome and Welcome.
An example of the generated HTML is as follows:
<li><a href="#welcome">Welcome</a></li>
<li><a href="#your-first-day">Your First Day</a></li>Block mapping will allow me to create more complex layouts in Jekyll using YAML Front Matter.
Final thoughts
The idea behind the Next handbooks is to document our culture, processes and tools. Anyone at Next can contribute to the them and those outside get an insight in to who we are and how we work.