Skip to content

Markdown Notes

RackN documentation is written in Markdown as scoped by mkdocs and its plugins.

The following docs are helpful for finding markdown and mkdocs cheats.

  • General setup of mkdocs features
  • Details of custom [markdown] and mkdocs options (
  • Python markdown information
  • mkdocs User Guide
  • awesome-pages plugin for better nav configuraiton
  • tags in mkdoc notes - talks about how they work - DETAILED
  • mike builds the docs in our CI/CD pipeline and provides the versioning by branch.
  • mike / gitlab integration notes
  • Main repo with docs for local development
  • Giscus is configured to go to our repo in github.


Each file should start with a header similar to the following example.

title: This is Also the Doc Title (# This is Also the Doc Title)
  - writers
  - contributing

Do not use the top-level heading as it is covered in the header. Headings should start with '##' and so on.


Tags that are allowed can be found in mkdocs.yml. At least one of the following tags should be used first: operator, developer, resources, reference, explanation, howto.

Tag Sets

The tags used are agregated into tag sets. You can find a breakdown of tag sets in The tags/<tag>.md entries will take tags listed under them and group any docs with both the tag and any subsequent tags. This populates the docs/tags/<tag>.md documents at build.

While not part of markdown, RackN docs can generate dynamic links that are build as part of the build process. These are similar to the Sphinx RST links, but have some specific caveats.

Marking Sections

Reference links can only be used on section headers. These have the form of section marker (###), a title (Marking Sections), and a mark ({#rs_md_marks}).

Example - All Put Together

### Title of section {#rs_section_reference}


The section can be of any depth to be marked, but must be of the # variety and its sub-peers.


Section titles that use : will have that converted to - for tagging and display purposes.


The RST form if underline and similar section notation is not able to support the marks.

Referencing Marks

To reference a mark, you will need to use the link format. The text inside the [] is replaced with the title of the section. The reference is replaced with a relative link to the


This is a [link](#rs_md_ref_marks_bb)


The _bb is used to keep the reference from rendering in this example.

The following is the rendered reference markdown.

This is a [Referencing Marks](../home/

Additionally, references can cross the refs and core boundaries. The system will convert the references to external https links when referencing marks in the other documentation tree. This is automatically done.

Image Helpers

To reference an image in the top-level images directory, a link helper has been added, images#.




The _bb is used to keep the reference from rendering in this example.

The following is the rendered reference markdown.