Introduction

You have code, and you need an easy way to document it. You might even want the docs to live in the github pages branch of the code’s repository. If you are using Python, we recommend Sphinx documentation built automatically on readthedocs, but this may be too complicated, or not suitable for your needs. This is RedDocs, with substantial thanks to mkdocs material,. We have added a front page and jekyll-ized that theme, adding automatic generation of pages and navigation for docs.

Here we’ll show you what RedDocs looks like and how you will use it. Take a look to the left. There is a sidebar with links, and contents (what you are reading now). When you click the link it scrolls to the section, and that’s it.

Let’s get started!

Set Up

The general idea is that you are going to be able to host this on github-pages, which is available to anyone with a Github account. We have provided a Dockerized development environment, unless you want to install Jekyll yourself.

When you are ready to go, you can download the theme, and then start developing your site. Just navigate to the folder, open a terminal and type:

jekyll serve

You will then be able to see the page at localhost:4000 and make your changes. When you are happy just push them to github in a gh-pages branch, or the master branch of your organization or user, and you’re site will be compiled by GitHub for you.

_config.yml

There is very few configuration to be done before you are up and running, still the ones you need to add, are as follows:

In the _config.yml-file:

# name of the docs
name: Stanford Documentation Template

# docs author
author: Stanford Research Computing

# docs version
version: V 1.0

All of these, minus the version, will be displayed on the top left-hand corner.

Content

Let’s get to the meat of your docs - your content! How does it work?

The only thing you need to care about are the files in the _entries folder. Each of these will be written separately and then be compiled into one single HTML file (index.md). This ensures that the output is minimal.

Collection Entries

Okay, so the collection is the entries collection. All of your documentation sections will be placed within that folder. The index file will then go over every one of these and put them together.

There are different ways on how you can take care of the order of the entries, depending on which one you chose, you will either have to work with filenames, or with the number front matter.

If you decide to work with file-names, you will just prefix your file names with numbers.

Section Types

There are three different levels supported, basically four, but the h4 tags will not be included, within the navigation by default. Read on if you want to change that.

Level one

If you want to create one of the main sections, you will need to include the following front matter within your entry:

---
sectionid: UNIQUE-ID
sectionclass: h1
title: TITLE
---

If you want your section to have subsections, add

is-parent: yes

The ID is important, because it will be used as the anchor for the scrollToLinks and it is also used within the subsections. So each child needs to tell jekyll what its parent is, before it can be placed correctly.

Level two

A Subsection of a level-2 will look like this

---
sectionid: UNIQUE-ID
sectionclass: h2
title: TITLE
parent-id: UNIQUE-ID-Of-PARENT
---

So the parent-id is where you will reference the anchor of the h1 section that’s your subsections parent.

Level 2 sections can have children, the variable to use is the same. To have children add

is-parent: yes

Level three

A Subsection of a level 3 will look like this

---
sectionid: UNIQUE-ID
sectionclass: h3
title: TITLE
parent-id: UNIQUE-ID-Of-PARENT
---

So the parent-id is where you will reference the anchor of the h2 section that’s your subsections parent.

Level 3 sections can have children, the variable to use is the same. To have children add

is-parent: yes

Level four

A Subsection of a level 4 will look like this

---
sectionid: UNIQUE-ID
sectionclass: h4
title: TITLE
parent-id: UNIQUE-ID-Of-PARENT
---

So the parent-id is where you will reference the anchor of the h3 section that’s your subsections parent.

Level 4 sections can’t have any more children within sections, but you if you add a h5 title, it will still have the numbering.

Order

There are two options on how to determine ordering of the sidebar links, and we’ve taken a combined version - using a four digit number to sort and represent the actual markdown docs, and then definining the equivalent number variable within the doc.

You can choose to change this standard, and the two options are detailed below.

File Names

The first option is just prefixing all of your files with file names.

So your files might look something like this:

├── 01 intro.md
│
├── 02 set_up.md
│
├── 02-01 config.md
│
├── 02-02 sass.md
│
├── 03 content.md
│
├── 03-01 collection_entries.md
│
├── 03-01-01 section_types.md
│
├── 03-01-01-01 level_one.md
│
├── 03-01-01-02 level_two.md
│
├── 03-01-01-03 level_three.md
│
├── 03-01-01-04 level_four.md
│
└── and so on...

Front Matter

For the second version (implemented for this demo), you define a font matter variable number So to go with the files from before, this is what this method would look like (under the file name, the front matter.) Note that we’ve also named the files with this number, so it’s transparent without needing to open them, and the files are sorted correctly.

├── 1000_intro.md
│   └── number: 1000
│
├── 2000_set_up.md
│   └── number: 2000
│
├── 2100_config.md
│   └── number: 2100
│
├── 3000_content.md
│   └── number: 3000
│
├── 3100_collection_entries.md
│   └── number: 3100
│
├── 3110_section_types.md
│   └── number: 3110
│
├── 3111_level_one.md
│   └── number: 3111
│
├── 3112_level_two.md
│   └── number: 3112
│
├── 3113_level_three.md
│   └── number: 3113
│
├── 3114_level_four.md
│   └── number: 3114
│
└── and so on...