Noir Docs

This is the source code for the Noir documentation site at noir-lang.org.

This website is built using Docusaurus 3, a modern static website generator.

Note: The docs folder is now a standalone project and no longer part of the main Noir yarn workspace. This change was made to resolve conflicts with Netlify deployments.

Contributing

Interested in contributing to the docs?

Check out the contributing guide here.

Development

Prerequisites

• Node.js (tested and working with v21.6.1)
• Yarn (tested and working with v4.5.2)

Installation

This project requires recent versions of Rust and Cargo to be installed. Any build errors should indicate dependencies that need installing, and at what version.

Navigate to the docs directory and install dependencies:

cd docs
yarn install

Local Development

From the docs directory:

1. Fetch and generate the list of recent stable documentation versions to build:

yarn version::stables

2. Start a development server serving docs preview:

yarn dev

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

From the docs directory:

1. Fetch and generate the list of recent stable documentation versions to build:

yarn version::stables

2. Build the docs:

yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

3. Verify build by serving a preview locally:

yarn serve

Production Testing

The site will be deployed at noir-lang.org/docs/. Test production configuration locally:

Simple Test

yarn production:serve

Access at: http://localhost:3000/docs/

Cutting a New Version

When a new Noir version is released, a versioned snapshot of the docs needs to be created. This is normally done automatically by the release workflow (.github/workflows/release.yml), but can also be done manually.

From the docs directory, run:

yarn cut_version <VERSION>

For example: yarn cut_version v1.0.0-beta.20

This script does three things:

1. Removes the new version from versions.json (since yarn version::stables will have added it from the GitHub release, but the versioned docs snapshot doesn't exist yet).
2. Builds the docs (running preprocessing to resolve #include_code directives and generate the Nargo CLI reference).
3. Runs yarn docusaurus docs:version <VERSION> to snapshot the current docs into versioned_docs/version-<VERSION>/ and create a matching sidebar in versioned_sidebars/.

After this, the new version will appear in the version dropdown on the site.

Important: The #include_code directives must be resolved before the snapshot is taken. The versioned_docs/ directory should never contain raw #include_code directives — CI will reject PRs that introduce them.

Quick Commands Reference

All commands should be run from the docs directory:

Command	Description
yarn install	Install dependencies
yarn dev	Start development server
yarn build	Build production site
yarn serve	Serve built site locally
yarn version::stables	Update stable versions list
yarn cut_version <VERSION>	Cut a new versioned docs snapshot
yarn clean	Clean build artifacts