See the Nais handbook for a more detailed explanation of the documentation structure and how to contribute.
Tenant values — environment names, ingress domains, external IPs, Kafka pools,
log destinations, deploy values and frontend collector URLs — come from the
public nais-tenant-data GCS bucket, written by nais-terraform-modules on every
apply (docs/<tenant>/tenant.json and docs/<tenant>/<env>.json). The build
discovers tenants by listing that bucket, so new tenants appear in the docs
without any commit to this repo. Missing data renders placeholders rather than
failing the build.
Use these macros instead of hardcoding environment-specific values:
| Macro | Output |
|---|---|
<<external_ips("prod")>> |
Bullet list of the environment's outbound IPs (env name is the Terraform env name) |
<<kafka_pools()>> |
Table of the tenant's Kafka pools, or a "no pools" note |
<<log_destinations()>> |
List of the tenant's log destinations |
<<default_log_destination()>> |
The tenant's default log destination (prod env's default, else first env's) |
<<example_domain("external")>> |
Representative ingress domain for examples (external or internal) |
<<management_project_id()>> |
Management GCP project id (deploy examples) |
<<identity_provider()>> |
GitHub OIDC workload identity provider resource name |
<<publishes_deploy_data()>> |
Whether the tenant publishes deploy data (for {% if %} conditions) |
<<telemetry_collectors()>> |
Collector endpoint table |
<<telemetry_csp_sources()>> |
Collector origins for CSP connect-src |
<<telemetry_collector_url()>> |
Example collector URL, preferring a production environment |
<<telemetry_environment()>> |
Environment used by the example collector URL |
Iterate a tenant's environments with {% for env in environments() %} — see
svdoc/INSTRUCTIONS.md for the loop syntax and available record fields.
Local development defaults to nav when TENANT is unset.
If a page should have a warning about not being available in test-nais, add the following near the top of the page:
<<not_in_test_nais("Name of feature")>>Add the following to the frontmatter of the page:
conditional: [not-test-nais, not-nav]Add the following to the frontmatter of the page:
conditional: [tenant, nav, ssb]
^^^^^^--- the keyword "tenant" is required to exclude all not mentionedAdd selected entry-point pages to llms.txt with global ordering metadata:
llms:
section: Workloads
order: 30Pages are grouped by section and ordered by the numeric order. Every
rendered documentation page is also available as Markdown at its canonical
path with a .md suffix; the root README.md is /index.md.
Four agents handle documentation tasks:
@research-agent → @technical-writer → @plain-language-en → @docs-qa
@research-agent— Investigates Nais source repos via GitHub MCP. Read-only.@technical-writer— Writes/edits docs following repo conventions (Diataxis, mkdocs, Jinja macros).@plain-language-en— Copy-edits for plain language, removes AI jargon.@docs-qa— Verifies docs accuracy against Nais source code. Read-only.
Start with @research-agent to gather context, hand off to @technical-writer to draft, which auto-hands off to @plain-language-en for polish. Then hand off to @docs-qa to verify accuracy against source code. Use @docs-qa standalone to audit any existing page.
The documentation site lives in svdoc/ and uses SvelteKit, Node.js and pnpm. Tasks are managed with mise.
Follow the mise installation guide. Node.js and pnpm are pinned in mise.toml and installed automatically.
mise run setupmise run localThis installs dependencies (if needed) and starts the dev server.
TENANT=nav NOT_TENANT=not-nav mise run local:devBuild all tenants (discovered from the nais-tenant-data bucket) into out/<tenant>/:
mise run buildOr build specific tenants:
mise run build nav test-naismise run check # run all checks
mise run check:lint # prettier + eslint
mise run check:svelte-check # svelte-check only
mise run check:test # Vitest unit tests
mise run check:ratchet # verify GitHub Actions are SHA-pinned
mise run fmt # format with prettierPull requests run all checks in CI. Ratchet is pinned in mise.toml.
Pin new GitHub Actions before opening a pull request:
mise exec -- ratchet pin .github/workflows/*.ymlpnpm requires package versions to be at least seven days old. Version-specific
exceptions in svdoc/pnpm-workspace.yaml keep the existing lockfile installable.
Remove exceptions once those versions are seven days old. Dependabot groups minor and patch
updates. Major updates get separate pull requests, except TypeScript majors,
which are ignored until the tools support them.