Skip to content
naisPublic

About

Nais developer documentation

Resources

Stars

69 stars

Watchers

58 watching

Forks

Latest commit

 

History

4,152 Commits

Folders and files

Repository files navigation

Welcome to the Nais documentation

See the Nais handbook for a more detailed explanation of the documentation structure and how to contribute.

Tools for working with tenants

Environment and collector data

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.

Warning about features not available in test-nais

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")>>

Exclude a full page from one or more tenants documentation

Add the following to the frontmatter of the page:

conditional: [not-test-nais, not-nav]

Include a page only for one or more tenants

Add the following to the frontmatter of the page:

conditional: [tenant, nav, ssb]
              ^^^^^^--- the keyword "tenant" is required to exclude all not mentioned

llms.txt curation

Add selected entry-point pages to llms.txt with global ordering metadata:

llms:
  section: Workloads
  order: 30

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

Copilot Agents

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.

Local development

The documentation site lives in svdoc/ and uses SvelteKit, Node.js and pnpm. Tasks are managed with mise.

1. Install mise

Follow the mise installation guide. Node.js and pnpm are pinned in mise.toml and installed automatically.

2. Install dependencies

mise run setup

3. Serve the documentation locally

mise run local

This installs dependencies (if needed) and starts the dev server.

3a. Serve a tenant-specific version of the documentation

TENANT=nav NOT_TENANT=not-nav mise run local:dev

4. Build the documentation

Build all tenants (discovered from the nais-tenant-data bucket) into out/<tenant>/:

mise run build

Or build specific tenants:

mise run build nav test-nais

Checks and formatting

mise 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 prettier

Pull 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/*.yml

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

About

Nais developer documentation

Resources

Stars

69 stars

Watchers

58 watching

Forks

Used by

Contributors

Languages