# 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 XML file and add an `xi:include` element 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.