mirror of https://github.com/NixOS/nixpkgs.git synced 2024-11-22 23:13:19 +00:00

While the word 'simply' is usually added to encourage readers, it often has the
opposite effect and may even appear condescending, especially when the reader
runs into trouble trying to apply the suggestions from the documentation. It is
almost always an improvement to simply drop the word from the sentence.

(there are more possible improvements like this, we can apply those in separate
PRs)

2023-11-09 21:48:05 +01:00

3.6 KiB

Raw Blame History

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$ devmode

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 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.

3.6 KiB Raw Blame History