Home • Explore • Blog • Models • CI
☰



nixpkgs
1st chunk of `pkgs/by-name/ni/nixos-render-docs/README.md`
4e13fe7653261038f1deffe40a3bc16d1ada8cc9a9fd5c500000000100000a0a
# 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.
Title: NixOS Render Docs: Documentation Renderer and Redirects System
Summary
`nixos-render-docs` is a custom CommonMark and man-pages renderer for the NixOS and Nixpkgs manuals. It implements RFC 72, facilitating the lossless migration of documentation from DocBook to CommonMark with custom extensions. The project justifies maintaining its own rendering framework by citing advantages such as avoiding tool limitations, preventing unexpected breakage, and adapting to evolving requirements without external dependencies. The document also describes a 'Redirects system' that integrates with the rendering process to extract content metadata and validate redirects. This system identifies removed/renamed identifiers and moved content, generating client-side and Netlify-compatible server-side redirects to prevent broken links, while balancing performance, repository size, and contributor experience with fast, local checks.