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:
And the code to generate the table of contents in the layout:
In the code sample above
chapter gets the key and
chapter the value of the pair, i.e.
An example of the generated HTML is as follows:
Block mapping will allow me to create more complex layouts in Jekyll using YAML Front Matter.
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.