annotations

frequenz.repo.config.mkdocs.annotations

Code annotations using numbers.

This module is provided almost exclusively as a documentation source.

Introduction

Normally annotations are shown with a (+) button that expands the annotation. To be able to explain code step by step, it is good to have annotations with numbers, shown as (1), (2), etc., to be able to follow the notes in a particular order.

To do this, we need some custom CSS rules. Before this customization was officially supported and documented, but now they are not officially supported anymore, so it could eventually break (it already did once).

If that happens we either need to look into how to fix the CSS ourselves or remove the feature. To do the customization, this is what we should be able to count on:

You can be sure that the data-md-annotation-id attribute will always be present in the source, which means you can always number them in any way you like.

How to implement it

To implement numbered annotations, you need to add a custom CSS file to your mkdocs.yml configuration file:

mkdocs.yml

extra_css:
  - path/to/style.css

The CSS file should contain the following rules:

path/to/style.css

.md-typeset .md-annotation__index > ::before {
  content: attr(data-md-annotation-id);
}
.md-typeset :focus-within > .md-annotation__index > ::before {
  transform: none;
}
.md-typeset .md-annotation__index {
  width: 4ch;
}

Macros integration

If you want to show an example on how an annotation looks like, you can use the CODE_ANNOTATION_MARKER variable to inject the appropriate HTML code. See frequenz.repo.config.mkdocs.mkdocstrings_macros for more information.

References

• Code annotation in mkdocs-material

• Original docs on how to enable numbered annotations

• The PR fixing the numbered annotations when they broke

• The regression reported when it was decided to drop support for numbered annotations officially

• The sphinx-immaterial documentation on how to do numbered annotations

Attributes

frequenz.repo.config.mkdocs.annotations.CODE_ANNOTATION_MARKER module-attribute

CODE_ANNOTATION_MARKER: str = (
    '<span class="md-annotation"><span class="md-annotation__index" tabindex="-1"><span data-md-annotation-id="1"></span></span></span>'
)

A variable to easily show an example code annotation.