Guideline for managing a documentation using the Jekyll Documentation theme

How To …

… manage a documentation site with the Jekyll Documentation theme

A documentation of the Documentation theme is available

Key issues are

  • The navigation is done by the horizontal bar at the top of each page and by vertical sidebars which may be different for different Books included into the site.
  • Page file structuring and naming
  • Site parameters
  • Layout customization

Be aware that there is a strong and strict relationship between the setup of the navigation and the page names. Read also the section about pages. In fact you have to know the file names of the pages first and only then you can create the navigation. On the other hand you have to know the sidebar navigation file names for the setup of pages.

Top Navigation

The content defined by ROOT/_data/sidebars/topnav.yml

The layout is defined by ROOT/_includes/topnav.html

One should follow these simple design rules:

  • A site may have one to many sidebar navigations. A guideline is: a sidebar navigation for the overall information about the site and a sidebar navigation for each of its Books.
  • A sidebar is defined by a file in the ROOT/_data/sidebars/ folder. A sidebar file’s name must be used for all pages which should show it.
  • A sidebar navigation lists all pages it should cover by file name. At the time of the creation of a sidebar file the files of the pages don’t have to exist already but created page files must adopt the name from the sidebar definition.

Pages

Be aware that there is a strong and strict relationship between the setup of the navigation and the page names. Read also the section about navigation. In fact you have to know the file names of the pages first and only then you can create the navigation. On the other hand you have to know the sidebar navigation file names for the setup of pages.

Creating a Page

Each page needs to have a frontmatter section at the top (delimited by lines with — only). Further it should include the content. As the Documentation theme doc shows Markdown markup and HTML can be mixed: in *.html files the HTML code takes precence and Markdown may be included with a special HTML element attribute, in *.md files Markdown can be used predominantly and some HTML may be inserted.

Naming Pages - and more

All page content is held inside the ROOT/pages folder.

To get a decent overview of the many pages of a site they may be grouped by sub-folders of the pages folder. This has not impact on the URL of a page, the file name of any page is appended to the base URL of a site.

By that background it makes sense to create a subfolder of ROOT/pages for the overall information about the site and for each of the Books provided by the site. But as the folders are not reflected by the page URLs, see above, it helps a lot to add a typical prefix for each of the groups (= folders), e.g. “home_”, “book1”, “book2” etc

Site Parameters

The key file with site parameters is ROOT/_config.yml. Details are explained in the Documentation theme doc.

Many specific parameter files reside in the ROOT/_data folder.

Layout Customization

In general the layout of the site is controlled by files in the ROOT/_layouts, ROOT/_includes, ROOT/css and ROOT/fonts folders.

The files defining specific page layout types are in the ROOT/_layout folder. File defining parts of a page across different page layout types are in the ROOT/_includes folder.

Files which are typically adjusted to the design of a specific site are in the ROOT/_includes/custom folder. A file there which must be edited with the design of the navigation is the sidebarconfigs.html as it must reflect the names of the sidebar navigations.

Modifying the Theme

Adopting a Jekyll theme requires to align it with some organisation-specific needs. Some of the code for that can be found in files clearly dedicate to customization. Other things, like adding the company logo, needs changes in regions considered as “part of the theme”. As this theme, like in fact all other Jekyll themes, is managed by a Github repository an update can be expected. Currently, late summer 2016, the theme shows version number 6.0, in spring version 5.0 was published. If one wants to use a theme for a long period it is required to check how easy theme updates can be adopted - practise will show that.