Skip to content

Markdown Notes

RackN documentation is written in Markdown as scoped by mkdocs and its plugins. RackN uses autorefs and its own reference system to enable cross page and redirection to references.

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.

Page 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
---

A top-level heading is optional. If not used, the title of the page or the nav title will be used from mkdocs.yaml.

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

# Cool Header {#rs_cool_header}

Note

It is often helpful to use a top-level heading for adding a named anchor..

Tags

Tags that are allowed can be found in mkdocs.yml. Tags must be specified in both the refs and core mkdocs.yml files. Tags not in the mkdocs.yml files will cause the building of docs to fail.

Each page should have one of these tags to define the primary audience of the document:

  • operator
  • developer
  • architecture

Each should have one of these tags to define the primary style of the document:

  • reference
  • explanation
  • howto
  • tutorial

Additional tags should be added to help for collecting related documents together in Tag Sets.

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.

Within Markdown, a section could be referenced by name within a page. For RackN documentation, we've added the autorefs plugin that allows for cross page references, the attr_links extension that allows for additional references, and our own processor that allows for redirection to references through javascript lookups.

We have all these options to enable the multiple ways our docs are consumed and referenced.

Marking Sections (Anchors)

The first method for defining an anchor is on a header directly.

# Cool Header {#rs_cool_header}

Both the RackN references and the autorefs plugin will store the Header title for use in reference expansion. This is helpful for references using consistent terms for aligning with the header.

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.

Floating Anchors

The floating anchor takes the following form:

[](){#rs_my_anchor}

This anchor can be in front header to allow for multiple references.

[](){#rs_my_anchor_header_2}
# Cool Example Header {#rs_cool_example_header}

The Cool Example Header section will be referenced by both the rs_my_anchor_header_2 and rs_cool_example_header anchors.

Note

The autorefs system will look ahead and store the title of the floating anchor as the next header. The RackN system will not. This means that when using the floating anchor you should provide a title in the reference.

Additionally, non-header based anchors can be added to the pages amongst text. In this case, no titles will be stored and a title must be provided in at the reference point.

Text pieces one and more.

[](){#rs_my_anchor_header_of_text_two}
Text pieces two and more.

Note

The use of non-header anchors in references requires title text in the reference.

Referencing Anchors

There are three ways to reference an anchor.

  • Internal Link
  • Autorefs Internal Format
  • Redirect

Each of these have different uses depending upon where the link is being created. RackN docs are used in three main places.

  • Interal - Rendered Documentation Site
  • Content - UX Rendered Documentation Fields
  • External - RackN Website (and others) External Refeence

Pages inside the documentation tree or built for use only in the documentation tree (e.g. release notes) are Internal. These pages can use the Internal Reference.

Content are pieces of the documentation that live in the content packs, plugins, and other delivered pieces that get rendered in both the documentation and the UX. These should use External Reference In Content to enable full function in both the docs and the UX. These require manual titling. Internal Reference will work within in the documentation, but will not work in the UX.

External are pages outside of the documentation, e.g. the RackN website. These are redirects that use the reference to get to the page without have to know the full path. These require manual titling. See What is this? or External References

Internal Reference

To reference an anchor from within the docs tree, you will need to use the link format or the autorefs format. The text inside the [] is maintained as the displayed text. If it is blank, the title from the reference will be used if known.

Autoref format

[Optional Title][tag-without-the-hashtag]

This style of reference works within the core subtree or the refs subtree, but not across sites. It will find the closest header for floating anchors. If the floating anchor is in the middle of text, a title must be provided.

[Optional Title](#tag-with-the-hashtag)

This is the normal reference in markdown. The reference is replaced with a file and anchor reference. The title will be filled if it is associated with specific header tag. Otherwse, a title is required. This format requires the hashtag.

Example

This is a [link](#rs_md_ref_marks_bb_warn_ok)

This is a [](#rs_md_ref_marks_bb_warn_ok)

Note

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

The following is the rendered reference markdown.

This is a [link](../home/markdown.md#rs_md_ref_marks)

This is a [Referencing Anchors](../home/markdown.md#rs_md_ref_marks)

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.

External Reference In Content

[Title](https://docs.rackn.io/stable/redirect/?ref=rs_model_template)

This allows everything a direct access to the underlying reference with redirection to the correct place. The main issue is around the fact that stable is built into the reference. This is required.

A title is also required because external renders, e.g. the UX, does not have the map to generate the titles.

External References

This is handled by the direct usage of a URL. See the What is this?.

Additional Internal to the Docs Helpers.

There are helpers to reference common images and built images.

Image Helpers

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

Example

![](images_bb#core_services.png)

![ports](images_bb#core_services.png)

Note

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

The following is the rendered reference markdown. 

![core_services.png](../images/core_services.png)

![ports](../images/core_services.png)

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

![](built_images_bb#arch-subnet.svg)

![subnet definition](built_images_bb#arch-subnet.svg)

Note

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

The following is the rendered reference markdown. 

![arch-subnet.svg](../built_images/arch-subnet.svg)

![subnet definition](../built_images/arch-subnet.svg)