Examples, Figures, Footnotes, Inline Comments, Link References, and Typographic Replacements in Documentation

: A brief explanation including when and when not to pass this attribute. : _Default:_ the output path's hash. ``` Checklist: - Start with a synopsis, to show the order of positional arguments. - Metavariables are in emphasized code spans: ``` *`arg1`* ```. Metavariables are placeholders where users may write arbitrary expressions. This includes positional arguments. - Attribute names are regular code spans: ``` `attr1` ```. These identifiers can _not_ be picked freely by users, so they are _not_ metavariables. - _optional_ attributes have a _`Default:`_ if it's easily described as a value. - _optional_ attributes have a _`Default behavior:`_ if it's not easily described using a value. - Nix types aren't in code spans, because they are not code - Nix types are capitalized, to distinguish them from the camelCase Module System types, which _are_ code and behave like functions. #### Examples To define a referenceable figure use the following fencing: ```markdown :::{.example #an-attribute-set-example} # An attribute set example You can add text before ```nix { a = 1; b = 2;} ``` and after code fencing ::: ``` Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents. Though this is not shown in the rendered documentation on nixos.org. #### Figures To define a referenceable figure use the following fencing: ```markdown ::: {.figure #nixos-logo} # NixOS Logo ![NixOS logo](./nixos_logo.png) ::: ``` Defining figures through the `figure` fencing class adds them to a `List of Figures` after the `Table of Contents`. Though this is not shown in the rendered documentation on nixos.org. #### Footnotes To add a foonote explanation, use the following syntax: ```markdown Sometimes it's better to add context [^context] in a footnote. [^context]: This explanation will be rendered at the end of the chapter. ``` #### Inline comments Inline comments are supported with following syntax: ```markdown  ``` The comments will not be rendered in the rendered HTML. #### Link reference definitions Links can reference a label, for example, to make the link target reusable: ```markdown ::: {.note} Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable. ::: [url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md ``` This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions). #### Typographic replacements Typographic replacements are enabled. Check the [list of possible replacement patterns check](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15). ## Getting help If you need documentation-specific help or reviews, ping [@NixOS/documentation-team](https://github.com/orgs/nixos/teams/documentation-team) on your pull request.

This section provides instructions on creating examples, figures, footnotes, inline comments, and link references within the documentation. It explains how to use specific markdown syntax for each element, including using the `example` and `figure` fencing classes. It also details how to add footnotes, inline comments, and link reference definitions. Finally, it notes that typographic replacements are enabled and provides a link to the replacement patterns. It mentions how to ping the NixOS documentation team for help with documentation-related pull requests.