Genestack Documentation Standards and Style Guide

This document is intended to help define some common documentation standards and practices for the Genestack documentation.

Introduction

The Genestack documentation is built using mkdocs-material with the source files located directly in the docs subdirectory of the Genestack project.

This page highlights some of the conventions and standards we strive to use across the Genestack documentation to hopefully provide a consistent reading experience for Genestack users.

Page Layout

Each page should start with a top-level heading (single #) with the tile of the page.

Subsections start with 2nd-level headings (double ##) and can have various levels nested underneath, 3rd-level (triple ###), 4th-level (quad ####), etc...

Markdown

While easy to use, Markdown does have some "gotchas" that make writing documentation interesting. It's easy to make some common mistakes when writing Markdown that can result in bad, illegible, or unintentionally humorous rendering issues.

This is mostly due to ambiguous information on how to implement certain edge-cases. CommonMark was one standard put in place to attempt to make this easier for authors.

Here are some notes on Markdown syntax used in mkdocs:

Headings

The headings (defined by #) should follow a natural progression of the hierarchy of the page contents. You cannot have two title headings otherwise they won't show up on the table of contents on the right side of the page:

# Title
## Main heading one
### Sub Heading one
### Sub heading two
## Main heading two

Links

Links should follow this syntax:

[Link](path to link)

If it is a link to another wiki page it should be a relative path:

[Installation](Installation)

and not like this:

[Installation](https://github.com/username/repo/wiki/Installation)

Instead, use that style for external links. Also, for external links, please add {:target="_blank"} at the end to have the link open in a new window:

[Google](https://google.com)){:target="_blank"}

Code Blocks

Inline

Inline code blocks are indicated with single backticks: `

`inline`

This will render as: inline

Code blocks

Code blocks are fenced with triple backtick fences

```
# code block
```

This will render as:

# code block

Bullets

Bullets are used to denote unordered lists. To have nested layers of bullets, you need to indent by 4 spaces for each nested layer bullet¹.

- Bullet
    - Sub bullet
        - Sub sub bullet

This will render like this:

• Bullet
  • Sub bullet
    • Sub sub bullet

NOTE: Markdownlint will complain, saying that you should indent by 2 unless you change or ignore rule MD007.

Numbering

Numbers will only order properly if in a listed sequence. If that sequence is broken by paragraphs then the numbering will restart.

Numbered lists are formatted as follows:

1. item 1
2. item 2
3. item 3
4. item 4

Symbols/Emojis

Emojis are not supported with python markdown and should be avoided. Rather important text should be bolded or italicized.

The following in github:

:exclamation:

renders to

but in the generated docs it will show

:exclamation:

Markdownlint

Using markdownlint on your files before you check them in can save you a lot of time and hassle. While some of mkdocs

You can use markdownlint from the CLI, or as a plugin in Visual Studio Code.

For other editors there are also solutions:

• For Emacs, there is markdown mode.
• For vim, there is a markdown plugin as well as a markdownlint plugin available.

Admonitions

Admonitions are used to highlight certain information to make it stand-out to readers.

Admonition Standards

It is important to have some documentation standards so that a user can understand how to process the information they read.

Custom Admonition Types