···106- [`note`](https://tdg.docbook.org/tdg/5.0/note.html)
107- [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)
108- [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)
0000000000000109110#### [Definition lists](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md)
111···139 Closes #216321.
140141- If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.
000000000000000000000000000000000000000000000000000
···106- [`note`](https://tdg.docbook.org/tdg/5.0/note.html)
107- [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)
108- [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)
109+- [`example`](https://tdg.docbook.org/tdg/5.0/example.html)
110+111+Example admonitions require a title to work.
112+If you don't provide one, the manual won't be built.
113+114+```markdown
115+::: {.example #ex-showing-an-example}
116+117+# Title for this example
118+119+Text for the example.
120+:::
121+```
122123#### [Definition lists](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md)
124···152 Closes #216321.
153154- If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.
155+156+## Documentation conventions
157+158+In an effort to keep the Nixpkgs manual in a consistent style, please follow the conventions below, unless they prevent you from properly documenting something.
159+In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label.
160+161+- Put each sentence in its own line.
162+ This makes reviewing documentation much easier, since GitHub's review system is based on lines.
163+164+- Use the admonitions syntax for any callouts and examples (see [section above](#admonitions)).
165+166+- If you provide an example involving Nix code, make your example into a fully-working package (something that can be passed to `pkgs.callPackage`).
167+ This will help others quickly test that the example works, and will also make it easier if we start automatically testing all example code to make sure it works.
168+ For example, instead of providing something like:
169+170+ ```
171+ pkgs.dockerTools.buildLayeredImage {
172+ name = "hello";
173+ contents = [ pkgs.hello ];
174+ }
175+ ```
176+177+ Provide something like:
178+179+ ```
180+ { dockerTools, hello }:
181+ dockerTools.buildLayeredImage {
182+ name = "hello";
183+ contents = [ hello ];
184+ }
185+ ```
186+187+- Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments. For example:
188+189+ ```markdown
190+ # pkgs.coolFunction
191+192+ Description of what `coolFunction` does.
193+ `coolFunction` expects a single argument which should be an attribute set, with the following possible attributes:
194+195+ `name`
196+197+ : The name of the resulting image.
198+199+ `tag` _optional_
200+201+ : Tag of the generated image.
202+203+ _Default value:_ the output path's hash.
204+205+ ```
+10
maintainers/team-list.nix
···96 shortName = "Blockchains";
97 };
98000000000099 c = {
100 members = [
101 matthewbauer