diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/contributing/contributing-to-documentation.chapter.md | 14 |
1 files changed, 5 insertions, 9 deletions
diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md index 889b4114accaf..a732eee4b9627 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -27,7 +27,7 @@ If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual. As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect. -Additional syntax extensions are available, though not all extensions can be used in NixOS option documentation. The following extensions are currently used: +Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used: - []{#ssec-contributing-markup-anchors} Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md). @@ -38,6 +38,10 @@ Additional syntax extensions are available, though not all extensions can be use ## Syntax {#sec-contributing-markup} ``` + ::: {.note} + NixOS option documentation does not support headings in general. + ::: + - []{#ssec-contributing-markup-anchors-inline} **Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…). @@ -67,10 +71,6 @@ Additional syntax extensions are available, though not all extensions can be use This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax. - ::: {.note} - Inline roles are available for option documentation. - ::: - - []{#ssec-contributing-markup-admonitions} **Admonitions**, set off from the text to bring attention to something. @@ -96,10 +96,6 @@ Additional syntax extensions are available, though not all extensions can be use - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html) - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html) - ::: {.note} - Admonitions are available for option documentation. - ::: - - []{#ssec-contributing-markup-definition-lists} [**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms: |