Nimiq Documentation Theme

Motivation

For the Nimiq Blockchain we wanted to design a documentation theme which has the following properties:

Installation

In your project’s root folder create a _config.yml like this:

remote_theme: nimiq/doc-theme
title: "Nimiq"
description: "Developer Reference"

Your readme.md will become your index.html.

Format

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 .md) into a beautiful HTML-based website that can be hosted directly from github.io. (See example below)

Just keep there rules in mind:

Real World Examples

Additional configuration

Following custom configuration can be added to the _config.yaml file.

Submodules

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:

And the title of the submodule section can be customized (default: “Submodules”).

submodules: "detailed"
submodule_section: "Sub-Projects"

Custom HTML

To add custom HTML to the header of the document, e.g. to add custom CSS, JavaScript, and more,

  1. Create a file with your custom HTML and put it into _includes
  2. Add the file name:
custom_header_tags: "custom-header-tags.html"

Exclude files

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).

Fedora/RedHat:

sudo dnf install ruby ruby-devel make gcc redhat-rpm-config zlib-devel

Debian/Ubuntu

sudo apt install ruby ruby-devel make gcc zlib-devel

Then, follow this guide but skip step 3.