Nixpkgs Documentation Syntax and Commit Conventions

Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-). #### 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} ``` > [!Note] > NixOS option documentation does not support headings in general. #### Inline Anchors Allow linking to an 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 `wrapGApps*` hook will prepend it to `XDG_DATA_DIRS`. ``` #### Automatic links If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example `[](#chap-contributing)`. This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing). #### HTML Inlining HTML is not allowed. Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual. #### Roles If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``. The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json). Please keep the `manpage-urls.json` file alphabetically sorted. A few markups for other kinds of literals are also available: - `` {command}`rm -rfi` `` - `` {env}`XDG_DATA_DIRS` `` - `` {file}`/etc/passwd` `` - `` {option}`networking.useDHCP` `` - `` {var}`/etc/passwd` `` These literal kinds are used mostly in NixOS option documentation. 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. They are handled by `myst_role` defined per renderer.  #### 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 ::: ``` The following are supported: - `caution` - `important` - `note` - `tip` - `warning` - `example` Example admonitions require a title to work. If you don't provide one, the manual won't be built. ```markdown ::: {.example #ex-showing-an-example} # Title for this example Text for the example. ::: ``` #### [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 ``` ## Commit conventions - Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole. - If creating a commit purely for documentation changes, format the commit message in the following way: ``` doc: (documentation summary) (Motivation for change, relevant links, additional information.) ``` Examples: * doc: update the kernel config documentation to use `nix-shell` * doc: add information about `nix-update-script` Closes #216321. - If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.

This section details the various syntax extensions supported for the Nixpkgs reference manual, beyond standard CommonMark Markdown. It covers GitHub-flavored Markdown tables, explicit heading and inline anchors, automatic link text for section references, and the prohibition of inline HTML. It also introduces 'roles' for linking to man pages or marking commands, environment variables, files, and options. The document further describes the use of admonitions (like warnings, notes, tips, and examples, with examples requiring a title) and definition lists. Finally, it outlines specific commit message conventions for documentation-only changes, recommending a 'doc: (summary)' format.