pyrox.dev
1# Contributing to the Nixpkgs manual
2
3This directory houses the sources files for the Nixpkgs manual.
4
5You can find the [rendered documentation for Nixpkgs `unstable` on nixos.org](https://nixos.org/manual/nixpkgs/unstable/).
6The rendering tool is [nixos-render-docs](../pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs), sometimes abbreviated `nrd`.
7
8[Docs for Nixpkgs stable](https://nixos.org/manual/nixpkgs/stable/) are also available.
9
10If you're only getting started with Nix, go to [nixos.org/learn](https://nixos.org/learn).
11
12## Contributing to this documentation
13
14You can quickly check your edits with `nix-build`:
15
16```ShellSession
17$ cd /path/to/nixpkgs
18$ nix-build doc
19```
20
21If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
22
23### devmode
24
25The shell in the manual source directory makes available a command, `devmode`.
26It is a daemon, that:
271. watches the manual's source for changes and when they occur — rebuilds
282. HTTP serves the manual, injecting a script that triggers reload on changes
293. opens the manual in the default browser
30
31## Syntax
32
33As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.
34
35Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:
36
37#### Tables
38
39Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-).
40
41#### Anchors
42
43Explicitly 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).
44
45It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:
46
47```markdown
48## Syntax {#sec-contributing-markup}
49```
50
51> **Note**
52> NixOS option documentation does not support headings in general.
53
54#### Inline Anchors
55
56Allow linking arbitrary place in the text (e.g. individual list items, sentences…).
57
58They 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):
59
60```markdown
61- []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.
62```
63
64#### Automatic links
65
66If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example `[](#chap-contributing)`.
67
68This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
69
70#### Roles
71
72If 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).
73
74A few markups for other kinds of literals are also available:
75
76- `` {command}`rm -rfi` ``
77- `` {env}`XDG_DATA_DIRS` ``
78- `` {file}`/etc/passwd` ``
79- `` {option}`networking.useDHCP` ``
80- `` {var}`/etc/passwd` ``
81
82These literal kinds are used mostly in NixOS option documentation.
83
84This 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.
85
86#### Admonitions
87
88Set off from the text to bring attention to something.
89
90It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):
91
92```markdown
93::: {.warning}
94This is a warning
95:::
96```
97
98The following are supported:
99
100- [`caution`](https://tdg.docbook.org/tdg/5.0/caution.html)
101- [`important`](https://tdg.docbook.org/tdg/5.0/important.html)
102- [`note`](https://tdg.docbook.org/tdg/5.0/note.html)
103- [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)
104- [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)
105
106#### [Definition lists](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md)
107
108For defining a group of terms:
109
110```markdown
111pear
112: green or yellow bulbous fruit
113
114watermelon
115: green fruit with red flesh
116```
117
118## Commit conventions
119
120- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole.
121
122- If creating a commit purely for documentation changes, format the commit message in the following way:
123
124 ```
125 doc: (documentation summary)
126
127 (Motivation for change, relevant links, additional information.)
128 ```
129
130 Examples:
131
132 * doc: update the kernel config documentation to use `nix-shell`
133 * doc: add information about `nix-update-script`
134
135 Closes #216321.
136
137- If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.