diff options
author | Jan Tojnar <jtojnar@gmail.com> | 2021-06-05 15:10:57 +0200 |
---|---|---|
committer | Jan Tojnar <jtojnar@gmail.com> | 2021-06-06 20:05:00 +0200 |
commit | ce6b1a4f8f9cbbb7fd2d1c637bcc39fff1ef49df (patch) | |
tree | 79fac9f237f3a61c773bbef103244b7b9ff19b91 | |
parent | 4a34590eced7ec7aadf4a64105d7a88125919738 (diff) |
doc: Document markup syntax
Not depicted: - Diagrams using Lua filter and dot - fenced code attributes (enabled by the attributes extension)
-rw-r--r-- | doc/contributing/contributing-to-documentation.chapter.md | 72 |
1 files changed, 71 insertions, 1 deletions
diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md index 7fd4b93f0d2b7..05b00d9bdda17 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -1,6 +1,6 @@ # Contributing to this documentation {#chap-contributing} -The DocBook sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository. +The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository. The manual is still partially written in DocBook but it is progressively being converted to [Markdown](#sec-contributing-markup). You can quickly check your edits with `make`: @@ -22,3 +22,73 @@ $ nix-shell ``` If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`. + +## Syntax {#sec-contributing-markup} + +As per [RFC 0062](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect. + +Additionally, the following syntax 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). + + It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax: + + ```markdown + ## Syntax {#sec-contributing-markup} + ``` + +- []{#ssec-contributing-markup-anchors-inline} + **Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…). + + They are defined using a hybrid of the link syntax with the attributes syntax known from headings, called [bracketed spans](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/bracketed_spans.md): + + ```markdown + - []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`. + ``` + +- []{#ssec-contributing-markup-admonitions} + **Admonitions**, set off from the text to bring attention to something. + + It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md): + + ```markdown + ::: {.warning} + This is a warning + ::: + ``` + + which renders as + + > ::: {.warning} + > This is a warning. + > ::: + + The following are supported: + + - [`caution`](https://tdg.docbook.org/tdg/5.0/caution.html) + - [`important`](https://tdg.docbook.org/tdg/5.0/important.html) + - [`note`](https://tdg.docbook.org/tdg/5.0/note.html) + - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html) + - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html) + +- []{#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: + + ```markdown + pear + : green or yellow bulbous fruit + + watermelon + : green fruit with red flesh + ``` + + which renders as + + > pear + > : green or yellow bulbous fruit + > + > watermelon + > : green fruit with red flesh + +For contributing to the legacy parts, please see [DocBook: The Definitive Guide](https://tdg.docbook.org/) or the [DocBook rocks! primer](https://web.archive.org/web/20200816233747/https://docbook.rocks/). |