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.
Reference Links¶
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}).
Note
The section can be of any depth to be marked, but must be of the # variety and its sub-peers.
Warning
Section titles that use : will have that converted to - for tagging and display purposes.
Warning
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 maintained as the
displayed text. If it is blank, the title from the reference will be used.
Example
Note
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 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#.
Example
Note
The _bb is used to keep the reference from rendering in this example.
The following is the rendered reference markdown.
Built Images¶
You can place a d2 file in the d2-images directory and the build will generate a file named the same but with an svg extension
in the src/built_images directory. Use the helper to reference the image.
Running the script, build_images.sh, will generate the images for development. You can additionally use the VSCode plugin to help with editing and previewing the images.
Built Images Helpers¶
To reference an builtimages in the top-level built_images directory, a link helper has been added, built_images#.
Example
Note
The _bb is used to keep the reference from rendering in this example.
The following is the rendered reference markdown.