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.
Each file should start with a header similar to the following example.
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:
The tags used are agregated into tag sets. You can find a breakdown of tag sets in
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.
Reference links can only be used on section headers. These have the form of section marker (
###), a title (
Marking Sections), and a mark (
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.
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
_bb is used to keep the reference from rendering in this example.
The following is the rendered reference markdown.
Additionally, references can cross the
core boundaries. The system will convert the references to external https links when referencing marks in the other documentation tree. This is automatically done.
To reference an image in the top-level
images directory, a link helper has been added,