depot/third_party/nixpkgs/nixos/doc/manual/development/writing-documentation.chapter.md

Writing NixOS Documentation

As NixOS grows, so too does the need for a catalogue and explanation of its extensive functionality. Collecting pertinent information from disparate sources and presenting it in an accessible style would be a worthy contribution to the project.

Building the Manual

The DocBook sources of the are in the nixos/doc/manual subdirectory of the Nixpkgs repository.

You can quickly validate your edits with make:

$ cd /path/to/nixpkgs/nixos/doc/manual
$ nix-shell
nix-shell$ make

Once you are done making modifications to the manual, it's important to build it before committing. You can do that as follows:

nix-build nixos/release.nix -A manual.x86_64-linux

When this command successfully finishes, it will tell you where the manual got generated. The HTML will be accessible through the result symlink at ./result/share/doc/nixos/index.html.

Editing DocBook XML

For general information on how to write in DocBook, see DocBook 5: The Definitive Guide.

Emacs nXML Mode is very helpful for editing DocBook XML because it validates the document as you write, and precisely locates errors. To use it, see .

Pandoc can generate DocBook XML from a multitude of formats, which makes a good starting point. Here is an example of Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML:

pandoc -f markdown_github -t docbook5 docs.md -o my-section.md

Pandoc can also quickly convert a single section.xml to HTML, which is helpful when drafting.

Sometimes writing valid DocBook is simply too difficult. In this case, submit your documentation updates in a GitHub Issue and someone will handle the conversion to XML for you.

Creating a Topic

You can use an existing topic as a basis for the new topic or create a topic from scratch.

Keep the following guidelines in mind when you create and add a topic:

• The NixOS book element is in nixos/doc/manual/manual.xml. It includes several parts which are in subdirectories.

• Store the topic file in the same directory as the part to which it belongs. If your topic is about configuring a NixOS module, then the XML file can be stored alongside the module definition nix file.

• If you include multiple words in the file name, separate the words with a dash. For example: ipv6-config.xml.

• Make sure that the xml:id value is unique. You can use abbreviations if the ID is too long. For example: nixos-config.

• Determine whether your topic is a chapter or a section. If you are unsure, open an existing topic file and check whether the main element is chapter or section.

Adding a Topic to the Book

Open the parent CommonMark file and add a line to the list of chapters with the file name of the topic that you created. If you created a section, you add the file to the chapter file. If you created a chapter, you add the file to the part file.

If the topic is about configuring a NixOS module, it can be automatically included in the manual by using the meta.doc attribute. See for an explanation.