# Contributing to this manual {#chap-contributing}

The sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository.
This manual uses the [Nixpkgs manual syntax](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup).

You can quickly check your edits with the following:

```ShellSession
$ cd /path/to/nixpkgs
$ $EDITOR doc/nixos/manual/... # edit the manual
$ nix-build nixos/release.nix -A manual.x86_64-linux
```

If the build succeeds, the manual will be in `./result/share/doc/nixos/index.html`.

There's also [a convenient development daemon](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-devmode).

The above instructions don't deal with the appendix of available `configuration.nix` options, and the manual pages related to NixOS. These are built, and written in a different location and in a different format, as explained in the next sections.

## Development environment {#sec-contributing-development-env}

In order to reduce repetition, consider using tools from the provided development environment:

Load it from the NixOS documentation directory with

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

To load the development utilities automatically when entering that directory, [set up `nix-direnv`](https://nix.dev/guides/recipes/direnv).

Make sure that your local files aren't added to Git history by adding the following lines to `.git/info/exclude` at the root of the Nixpkgs repository:

```
/**/.envrc
/**/.direnv
```

### `devmode` {#sec-contributing-devmode}

Use [`devmode`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/de/devmode/README.md) for a live preview when editing the manual.

## Testing redirects {#sec-contributing-redirects}

Once you have a successful build, you can open the relevant HTML (path mentioned above) in a browser along with the anchor, and observe the redirection.

Note that if you already loaded the page and *then* input the anchor, you will need to perform a reload. This is because browsers do not re-run client JS code when only the anchor has changed.

## Contributing to the `configuration.nix` options documentation {#sec-contributing-options}

The documentation for all the different `configuration.nix` options is automatically generated by reading the `description`s of all the NixOS options defined at `nixos/modules/`. If you want to improve such `description`, find it in the `nixos/modules/` directory, and edit it and open a pull request.

To see how your changes render on the web, run again:

```ShellSession
$ nix-build nixos/release.nix -A manual.x86_64-linux
```

And you'll see the changes to the appendix in the path `result/share/doc/nixos/options.html`.

You can also build only the `configuration.nix(5)` manual page, via:

```ShellSession
$ cd /path/to/nixpkgs
$ nix-build nixos/release.nix -A nixos-configuration-reference-manpage.x86_64-linux
```

And observe the result via:

```ShellSession
$ man --local-file result/share/man/man5/configuration.nix.5
```

If you're on a different architecture that's supported by NixOS (check file `nixos/release.nix` on Nixpkgs' repository) then replace `x86_64-linux` with the architecture. `nix-build` will complain otherwise, but should also tell you which architecture you have + the supported ones.