Change:
} ``` <ins> - 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. - When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples. Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation. The purpose of this convention is to provide a familiar structure for navigating the manual, so any reader can expect to find content related to inputs in an "inputs" heading, examples in an "examples" heading, and so on. An example: ``` ## buildImage Some explanation about the function here. Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it. ### Inputs Documentation for the inputs of `buildImage`. Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it. ### Passthru outputs Documentation for any passthru outputs of `buildImage`. ### Examples Note that this is the last nested heading in the `buildImage` section. :::{.example #ex-dockerTools-buildImage} # Using `buildImage` Example of how to use `buildImage` goes here. ::: ``` </ins> - Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments as well as their [types](https://nixos.org/manual/nix/stable/language/values). For example:

Discussion:
While working on some documentation on Nixpkgs, I noticed that there doesn't seem to be a convention for showing shell commands and their outputs. prepends to the command prompt, and output as a normal, not-indented line. adds a comment above the command prompt showing what the output is. uses two different code blocks, one with the command, the other with the output. Additionally, there are other code blocks to show expressions and their result inside the nix repl: prepends to the (error) output. And prepends to the output. Note that the proposal below was written just to have some starting proposal, but not much thought has been given to other alternatives yet. My current proposal is to adopt the following convention: For shell commands and outputs, prepend to any lines that are part of the command, and put outputs in their own lines as-is. If the command has line continuations, don't prepend , but add some indentation to keep it from looking like an output. For example: For nix repl expressions, prepend to any lines part of an expression, and put outputs in their own lines as-is. <!-- make sure this issue is not redundant or obsolete --- [x] checked [latest Nixpkgs manual] ([source][nixpkgs-source]) and [latest NixOS manual] ([source][nixos-source]) [x] checked [open documentation issues] for possible duplicates [x] checked [open documentation pull requests] for possible solutions [latest Nixpkgs manual]: [latest NixOS manual]: [nixpkgs-source]: [nixos-source]: [open documentation issues]: [open documentation pull requests]: Add a :+1: [reaction] to [issues you find important]. [reaction]: [issues you find important]:
Talked about this in the docs team meeting, I think this is a good idea! If you make a PR to describe this convention in the I could review/merge it. I guess very generally, the convention is to use the format as you'd see it in the REPL.
This issue has been mentioned on NixOS Discourse. There might be relevant details there: