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 (https://squidfunk.github.io/mkdocs-material/reference/)
  • 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.

Headers

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)
tags:
  - writers
  - contributing
---

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

Tags

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 mkdocs.md. 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.