pyrox.dev
1# Contributing to this documentation {#chap-contributing}
2
3The 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).
4
5You can quickly check your edits with `make`:
6
7```ShellSession
8$ cd /path/to/nixpkgs/doc
9$ nix-shell
10[nix-shell]$ make
11```
12
13If you experience problems, run `make debug` to help understand the docbook errors.
14
15After making modifications to the manual, it's important to build it before committing. You can do that as follows:
16
17```ShellSession
18$ cd /path/to/nixpkgs/doc
19$ nix-shell
20[nix-shell]$ make clean
21[nix-shell]$ nix-build .
22```
23
24If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
25
26## Syntax {#sec-contributing-markup}
27
28As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.
29
30Additional syntax extensions are available, though not all extensions can be used in NixOS option documentation. The following extensions are currently used:
31
32- []{#ssec-contributing-markup-anchors}
33 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).
34
35 It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:
36
37 ```markdown
38 ## Syntax {#sec-contributing-markup}
39 ```
40
41- []{#ssec-contributing-markup-anchors-inline}
42 **Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…).
43
44 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):
45
46 ```markdown
47 - []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.
48 ```
49
50- []{#ssec-contributing-markup-automatic-links}
51 If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example, `[](#chap-contributing)` will result in [](#chap-contributing).
52
53 This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
54
55- []{#ssec-contributing-markup-inline-roles}
56 If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/link-unix-man-references.lua`.
57
58 A few markups for other kinds of literals are also available:
59
60 - `` {command}`rm -rfi` `` turns into {command}`rm -rfi`
61 - `` {env}`XDG_DATA_DIRS` `` turns into {env}`XDG_DATA_DIRS`
62 - `` {file}`/etc/passwd` `` turns into {file}`/etc/passwd`
63 - `` {option}`networking.useDHCP` `` turns into {option}`networking.useDHCP`
64 - `` {var}`/etc/passwd` `` turns into {var}`/etc/passwd`
65
66 These literal kinds are used mostly in NixOS option documentation.
67
68 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.
69
70 ::: {.note}
71 Inline roles are available for option documentation.
72 :::
73
74- []{#ssec-contributing-markup-admonitions}
75 **Admonitions**, set off from the text to bring attention to something.
76
77 It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):
78
79 ```markdown
80 ::: {.warning}
81 This is a warning
82 :::
83 ```
84
85 which renders as
86
87 > ::: {.warning}
88 > This is a warning.
89 > :::
90
91 The following are supported:
92
93 - [`caution`](https://tdg.docbook.org/tdg/5.0/caution.html)
94 - [`important`](https://tdg.docbook.org/tdg/5.0/important.html)
95 - [`note`](https://tdg.docbook.org/tdg/5.0/note.html)
96 - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)
97 - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)
98
99 ::: {.note}
100 Admonitions are available for option documentation.
101 :::
102
103- []{#ssec-contributing-markup-definition-lists}
104 [**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms:
105
106 ```markdown
107 pear
108 : green or yellow bulbous fruit
109
110 watermelon
111 : green fruit with red flesh
112 ```
113
114 which renders as
115
116 > pear
117 > : green or yellow bulbous fruit
118 >
119 > watermelon
120 > : green fruit with red flesh
121
122For 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/).