nunit/docs is the DocFX pipeline behind docs.nunit.org

A documentation site treated as its own project

The repository's stated purpose is narrow and clear. It serves the content that is found at <https://docs.nunit.org>, and the README adds that the docs site is a project within the NUnit organization, with a pointer to VISION.md to understand more about how the documentation fits into the overall organization and how it supports the other projects.

That framing matters for anybody considering a contribution. A documentation repository that is a project inside an organisation has a scope, a maintainer structure and a place in a roadmap, rather than being the place where whoever has a spare afternoon improves the wording. The repository carries the usual companions of that kind of project: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `VISION.md`, a `renovate.json` for dependency updates and a `LICENSE.md`.

The technical footprint is small and mostly tooling. The primary language of the repository is recorded as Dockerfile, which is the dev container, and the top level holds `docs/` with the content, `tools/`, a `.devcontainer/` directory, a `.vscode/` directory, a `.tours/` directory for guided walkthroughs, `cSpell.json` for the spell checker, `nunit.vssettings` for the shared Visual Studio settings and a `.markdownlintrc`. The licence is MIT, the repository is not archived, and the last push was on 2026-10-18 with no GitHub releases published.

Building locally needs DocFX and nothing else exotic

The local build instructions are four steps, and the first one is the only prerequisite.

Install DocFX, which the README suggests doing with Chocolatey and the command `choco install docfx -y`. Then pull this repository, `cd docs`, and run `docfx serve` and navigate to <http://localhost:8080/_site>.

The shape of that is worth noting, because it determines what you can do as a contributor. DocFX is the engine that turns the Markdown in `docs/` into the published site, and serving it locally means you get the same output the production build produces, with live reload, on port 8080. There is no separate site generator to learn and no content pipeline of your own to set up, so the loop between editing a page and seeing it is as short as the toolchain allows.

The consequence is that a contributor needs a .NET toolchain on their machine even if they only intend to fix a sentence. That is the price of the documentation being generated from the same kind of tooling that generates the API pages, and the Codespaces setup below is the answer to it.

Codespaces turns the toolchain into four commands

The README offers a second route for people who would rather not install the toolchain themselves. The section is titled how to build these docs within GitHub Codespaces or a dev container, and it opens by offering both: open the branch you want to work on in GitHub Codespaces, or work in the environment locally.

The point of the approach is that the tooling, the VS Code extensions and everything else that is used are immediately available, so there is nothing to install. Then four commands do the work, and the README adds the same parenthetical to each of them, that the rest has been taken care of for you.

`build` builds the docs. `serve` serves and previews them. `lint` runs the markdown linting. `spellcheck` runs the spell check. There is a fifth in the list, `snippets`, to build and test the snippets.

The README is also honest about the maturity of this path. It says the team will be working on follow-ups to make this more user-friendly, but that it is now workable. That is a fair description of a dev container that already does the hard part, and the alternative, installing DocFX and a set of VS Code extensions by hand, is exactly the friction it removes.

The Windows and WSL failure has a one line fix

One failure mode is documented in enough detail to be useful, and it is the kind that costs an afternoon if you have never seen it.

If the image builds but the container fails to start with an error like this:

```text docker: Error response from daemon: accessing specified distro mount service: stat /run/guest-services/distro-services/ubuntu.sock: no such file or directory

then VS Code is trying to mount the WSLg Wayland socket from your WSL distro into the container, and Docker Desktop cannot reach that distro. The docs tooling does not need it, so the simplest fix is to turn it off in your VS Code user settings:

json "dev.containers.mountWaylandSocket": false ```

Then run Dev Containers: Rebuild and Reopen in Container. The README gives two alternatives as well: enable WSL integration for your distro in Docker Desktop under Settings, Resources, WSL integration, or run `wsl --shutdown` and restart Docker Desktop.

The diagnosis is the useful part here, since the error text mentions a socket path and a distro service that has nothing to do with documentation. The cause is a desktop integration feature that the docs container has no use for, and the fix is one setting rather than a reinstall.

Linting and spellchecking are part of the workflow

The repository treats text quality as a build concern rather than a review comment, and the tooling is specified in the README.

Install `markdownlint-cli2` with `npm install markdownlint-cli2 -g`, open the root of the project rather than the `docs` directory, and run the linter with the config path in `.github/linters` and a glob over the Markdown under `docs`.

The note about opening the root is the sort of detail that saves a confusing error, because the glob is relative to the repository root and the config path points into the linters directory.

For editors, the README recommends a VS Code setting so the problems are fixed as you type:

    "editor.codeActionsOnSave": {
        "source.fixAll.markdownlint": "always"
    }

and says this will fix 80% of the markdown linting issues for you upon save. The remaining 20% is the part that needs a human. There is also a `cSpell.json` in the repository root for the spell checker, and a `.markdownlintrc` alongside the more specific config the linter command uses.

For a project that accepts outside contributions, that combination is what keeps a large prose corpus reviewable. The automated checks handle the mechanical failures, and the human review handles the ones that matter.

The API reference is generated from the shipped binaries

This is the part of the pipeline that surprises people, and it is the reason the repository exists as a build project rather than a folder of Markdown.

The NUnit source code is in a separate repository from the docs, so the API reference is typically generated at build time by copying published code into a build-specific folder, `/code-output`. From there, DocFX transforms the xmldoc comments that are alongside the DLLs into HTML files.

So the API pages are not written by hand and not copied from the source tree. They are extracted from the compiled assemblies of a published release, which has two consequences. The reference is always consistent with the binaries it was built from, which is exactly what a reader of an API page needs. And the reference for a version that has not been released yet does not exist, because there are no DLLs to read the comments out of.

The README also explains how to reproduce the generation locally, which is useful when you want to see the reference for a specific release while working on the prose around it. Go to the NUnit release you want in the GitHub Releases, download and extract the zip file of the release contents, copy the contents of one of the release targets, for example `net6.0`, into a `code-outputs` folder in the root of the repository, and then run the `docfx` command as you normally would.

That is a self contained recipe, and it is the answer to the question of how a contributor checks that the API pages match a particular version.

Two containers and a branch move the site

The deployment path is described in four steps, and it is worth reading because it explains why a documentation change becomes visible on docs.nunit.org without anyone copying files.

The docs are built via the GitHub actions located in `./github/workflows`. The workflow uses a container with DocFX installed, and the container builds the docs. The workflow then uses another container to push the results to the `gh-pages` branch, using a personal access token that is stored in the repository's settings. GitHub serves the outputted site from the `gh-pages` branch, and the DNS of `docs.nunit.org` points there.

So the build artefact never sits in a branch of content. It is produced in a container, pushed to a dedicated branch, and served by GitHub's own pages infrastructure through a DNS record. The only secret involved is the token, and it lives in the repository settings rather than in the workflow file.

The practical consequence for a contributor is that the workflow is the source of truth for what gets published, so a change that looks right in a local `docfx serve` still has to pass the container build to go live. That is the trade for a documentation set that mixes hand written pages with reference pages generated from a separate source repository, and for a project where the documentation is a project with its own vision, contribution guide and code of conduct.

Editorial conclusion

Adopt the repository if you want to contribute to the NUnit documentation, and read it as the authoritative description of how the framework's user facing surface is produced and published. Do not expect it to be a source of API facts, since the reference pages are generated from the shipped assemblies at build time. Verify first that you have DocFX available before building locally, that you run the markdown linter from the repository root rather than from `docs`, that the API reference folder is populated from the release you intend to document, and that any local change you push is picked up by the workflow rather than only by your own `docfx serve`.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nunit/docs on GitHub
4. Project website
5. README