NixOS Documentation Rendering with nixos-render-docs

# nixos-render-docs A [CommonMark](https://commonmark.org/) and [`man-pages`](https://www.man7.org/linux/man-pages/man7/man-pages.7.html) renderer for the NixOS and Nixpkgs manuals. ## Summary `nixos-render-docs` implements [RFC 72](https://github.com/NixOS/rfcs/pull/72) and has enabled a lossless port of Nixpkgs and NixOS documentation, which was originally written in the [DocBook](https://docbook.org/whatis) format, to [CommonMark](https://commonmark.org/) with [custom extensions](../../../../doc/README.md#syntax). Maintaining our own documentation rendering framework may appear extreme but has practical advantages: - We never have to work around existing tools made under different assumptions - We don't have to deal with unexpected breakage - We can grow the framework with our evolving requirements without relying on external support or approval or the need to maintain a small diff to upstream - The amount of code involved is minimal because it's single-purpose Several alternatives to `nixos-render-docs` were discussed in the past. A detailed analysis can be found in a [table comparing documentation rendering framework](https://ethercalc.net/dc4vcnnl8zv0). ## Redirects system Moving contents around can cause links to break. Since we have our own markdown parser, we can hook into the rendering process to extract all of the metadata around each content identifier. The [mechanism for checking correctness of redirects](./src/nixos_render_docs/redirects.py) takes the collection of identifiers and a mapping of the identified content to its historical locations in the output. It validates them against a set of rules, and creates a client-side redirect mapping for each output file, as well as a `_redirects` file for server-side redirects in [Netlify syntax](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file). This allows us to catch: - Identifiers that were removed or renamed - Content that was moved from one location to another - Various consistency errors in the redirects mapping ### Design considerations The creation, movement, and removal of every identifier is captured in the Git history. However, analysing hundreds of thousands of commits during the build process is impractical. The chosen design is a trade-off between speed, repository size, and contributor friction: - Stricter checks always require more attention from contributors - Checks should be reasonably fast and ideally happen locally, e.g. as part of the build, as anything else will substantially lengthen the feedback cycle.

nixos-render-docs is a CommonMark and man-pages renderer for NixOS and Nixpkgs manuals, implementing RFC 72. It allows lossless porting of documentation from DocBook to CommonMark with custom extensions. The framework provides advantages like avoiding workarounds, preventing unexpected breakage, and adapting to evolving requirements. It also includes a redirects system to maintain link integrity when content is moved or renamed, catching errors and creating client/server-side redirects.