Admonitions, Definition Lists, Commit Conventions, and Documentation Conventions

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. ## Documentation conventions 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. In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label. When needed, each convention explain why it exists, so you can make a decision whether to follow it or not based on your particular case. Note that these conventions are about the **structure** of the manual (and its source files), not about the content that goes in it. You, as the writer of documentation, are still in charge of its content. ### One sentence per line Put each sentence in its own line. This makes reviews and suggestions much easier, since GitHub's review system is based on lines. It also helps identifying long sentences at a glance. ### Callouts and examples Use the [admonition syntax](#admonitions) for callouts and examples. ### Provide self-contained examples Provide at least one example per function, and make examples self-contained. This is easier to understand for beginners. It also helps with testing that it actually works – especially once we introduce automation. Example code should be such that it can be passed to `pkgs.callPackage`. Instead of something like: ```nix pkgs.dockerTools.buildLayeredImage { name = "hello"; contents = [ pkgs.hello ]; } ``` Write something like: ```nix { dockerTools, hello }: dockerTools.buildLayeredImage { name = "hello"; contents = [ hello ]; } ``` ### REPLs When showing inputs/outputs of any [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), such as a shell or the Nix REPL, use a format as you'd see in the REPL, while trying to visually separate inputs from outputs. This means that for a shell, you should use a format like the following: ```shell $ nix-build -A hello '<nixpkgs>' \ --option require-sigs false \ --option trusted-substituters file:///tmp/hello-cache \ --option substituters file:///tmp/hello-cache /nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1 ``` Note how the input is preceded by `$` on the first line and indented on subsequent lines, and how the output is provided as you'd see on the shell. For the Nix REPL, you should use a format like the following: ```shell nix-repl> builtins.attrNames { a = 1; b = 2; } [ "a" "b" ] ``` Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL. ### Headings for inputs, outputs and examples

This section outlines the use of admonitions and definition lists in Nixpkgs documentation, detailing their syntax and specific requirements. It also specifies the commit message format for documentation-only changes and emphasizes adherence to general Nixpkgs commit conventions for broader changes. Furthermore, it presents documentation conventions for maintaining a consistent style, including one sentence per line, using admonitions for callouts and examples, providing self-contained examples compatible with `pkgs.callPackage`, and standardizing the presentation of REPL interactions. Headings for inputs, outputs and examples are expected.