diff options
author | pennae <82953136+pennae@users.noreply.github.com> | 2023-01-30 19:26:07 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-01-30 19:26:07 +0100 |
commit | 5b6dcece880b1fe45532b383e1c1f9574ddac4cf (patch) | |
tree | 75ad5ae9002e3ff171eb95a0367456105bb7e121 /doc | |
parent | 8de8ee54bdceb257a05635e08c6021eb251720bd (diff) | |
parent | 0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9 (diff) |
Merge pull request #212684 from pennae/nixos-render-docs
nixos-render-docs: init, use for some manual rendering to docbook
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: |