Editing Documents

The preferred syntax for writing documents is MyST Markdown. You may alternatively use reStructuredText when starting a new document, but note that most developers will be more familiar with Markdown.

MyST Markdown (.md)

As Markdown usage is widespread, chances are high that you have encountered the syntax before and can get started right away. MyST is a strict superset of the CommonMark syntax specification, which adds features focussed on scientific and technical documentation authoring. Some of these additional features that we make use of in docs.postmarketos.org are shown below. Find the complete reference in the Authoring section of the MyST documentation.

Cross-references

In order to link to a section of a document, add a target to the headline as follows:

(heading-target)=
### Heading

You can then link to it from any document (!) inside the same Sphinx project like this:

[reference1](#heading-target)

Read more about this in MyST’s cross-references chapter.

Admonitions

Tip

Read this section when you have a helpful tip to add to your document.

The above tip is displayed with this code:

:::{tip}
Read this section when you have a helpful tip to add to your document.
:::

When used correctly, these admonitions can nicely highlight tips as well as important or dangerous sections and more. But make sure to not overuse them, if the page is covered in them then it becomes distracting and harder to read.

Read more about this in MyST’s admonitions chapter.

reStructuredText (.rst)

See the reStructuredText Primer chapter in the Sphinx documentation for a good overview.