···106106- [`note`](https://tdg.docbook.org/tdg/5.0/note.html)
107107- [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)
108108- [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)
109109+- [`example`](https://tdg.docbook.org/tdg/5.0/example.html)
110110+111111+Example admonitions require a title to work.
112112+If you don't provide one, the manual won't be built.
113113+114114+```markdown
115115+::: {.example #ex-showing-an-example}
116116+117117+# Title for this example
118118+119119+Text for the example.
120120+:::
121121+```
109122110123#### [Definition lists](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md)
111124···139152 Closes #216321.
140153141154- If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.
155155+156156+## Documentation conventions
157157+158158+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.
159159+In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label.
160160+161161+- Put each sentence in its own line.
162162+ This makes reviewing documentation much easier, since GitHub's review system is based on lines.
163163+164164+- Use the admonitions syntax for any callouts and examples (see [section above](#admonitions)).
165165+166166+- If you provide an example involving Nix code, make your example into a fully-working package (something that can be passed to `pkgs.callPackage`).
167167+ 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.
168168+ For example, instead of providing something like:
169169+170170+ ```
171171+ pkgs.dockerTools.buildLayeredImage {
172172+ name = "hello";
173173+ contents = [ pkgs.hello ];
174174+ }
175175+ ```
176176+177177+ Provide something like:
178178+179179+ ```
180180+ { dockerTools, hello }:
181181+ dockerTools.buildLayeredImage {
182182+ name = "hello";
183183+ contents = [ hello ];
184184+ }
185185+ ```
186186+187187+- Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments. For example:
188188+189189+ ```markdown
190190+ # pkgs.coolFunction
191191+192192+ Description of what `coolFunction` does.
193193+ `coolFunction` expects a single argument which should be an attribute set, with the following possible attributes:
194194+195195+ `name`
196196+197197+ : The name of the resulting image.
198198+199199+ `tag` _optional_
200200+201201+ : Tag of the generated image.
202202+203203+ _Default value:_ the output path's hash.
204204+205205+ ```