Nimiq Documentation Theme
For the Nimiq Blockchain we wanted to design a documentation theme which has the following properties:
- Is a Jekyll theme for GitHub Pages, thus very easy to add and use
- Works with multiple
- Automatically generates table of contents from filenames and headings
- Clean design focused on the content and its typography
- Mobile layout
In your project’s root folder create a
_config.yml like this:
remote_theme: nimiq/doc-theme title: "Nimiq" description: "Developer Reference"
readme.md will become your
Doc-theme is based on markdown.
Markdown is a simple text format that allows you to define links, headings, lists, tables, and more
(checkout this cheatsheet for details)
in a way that keeps the files still human readable and easy to edit.
Doc-theme with the help of Jekyll and Liquid (read more here)
turns these markdown files (files ending with
into a beautiful HTML-based website that can be hosted directly from
github.io. (See example below)
Just keep there rules in mind:
- Every page must have exactly one
# top-heading, it will be used in the navigation as label.
- The top heading should be the first line of each page.
- All other headings should be second-level headings like
## second-leveland below.
Real World Examples
Following custom configuration can be added to the
Doc-Theme automatically detects submodules, i.e. folder with a
README.md file inside.
These modules will then be place in a dedicated section at the bottom of the navigation bar.
Submodules can be shown:
brief(default, just show top-level of submodule README.md file),
detailed(also show second-level headings of each submodule
none(hide submodules section)
And the title of the submodule section can be customized (default: “Submodules”).
submodules: "detailed" submodule_section: "Sub-Projects"
- Create a file with your custom HTML and put it into
- Add the file name:
By default, all markdown files of all subfolders will be included into the resulting doc. The example below excludes node modules and hidden files like Git files:
exclude: ["node_modules/*", "./*/*/**"]
Test and Build your Documentation Locally
To test your documentation before pushing it live follow these steps to set up Jekyll for GitHub pages on your machine.
First, install all pre-requisits (this command will automatically skip what is installed already).
sudo dnf install ruby ruby-devel make gcc redhat-rpm-config zlib-devel
sudo apt install ruby ruby-devel make gcc zlib-devel
Then, follow this guide but skip step 3.