nais · thokra-nav · Apr 30, 2026 · Nov 25, 2025 · Nov 25, 2025 · Nov 25, 2025
diff --git a/.github/agents/technical-writer.agent.md b/.github/agents/technical-writer.agent.md
@@ -1,6 +1,6 @@
 ---
 name: technical-writer
-description: 'Write and edit Nais platform documentation following repo conventions (Diataxis, mkdocs Material, Jinja macros). Use when: creating new docs pages, restructuring existing docs, reviewing docs PRs, converting notes into proper documentation.'
+description: 'Write and edit Nais platform documentation following repo conventions (Diataxis, Material for MkDocs-style syntax, template macros rendered by the svdoc SvelteKit site). Use when: creating new docs pages, restructuring existing docs, reviewing docs PRs, converting notes into proper documentation.'
 tools: ['read', 'edit', 'search', 'web']
 handoffs:
   - label: Polish language
@@ -86,9 +86,9 @@ nav:
   - reference
 ```
 
-## Jinja2 Macros
+## Template Macros
 
-This repo uses `<<` and `>>` as Jinja delimiters (NOT `{{` `}}`).
+Markdown is rendered by the custom SvelteKit site in `svdoc/`, which supports a Jinja-like template syntax. This repo uses `<<` and `>>` as expression delimiters (NOT `{{` `}}`).
 
 Available macros:
 

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -1,7 +1,7 @@
 # GitHub Copilot Custom Instructions for nais/doc
 
 ## About this repository
-This repository contains the main documentation for the Nais developer platform, structured using the Diátaxis framework: Tutorials, How-To Guides, Explanations, and Reference and using mkdocs with Material for MkDocs as the documentation generator. Nais is a platform that simplifies the deployment and management of applications on Kubernetes (but without having in-depth knowledge of Kubernetes), providing tools and best practices for developers to streamline their workflows.
+This repository contains the main documentation for the Nais developer platform, structured using the Diátaxis framework: Tutorials, How-To Guides, Explanations, and Reference. Markdown sources live in `docs/` and are rendered by a custom SvelteKit + Bun site in `svdoc/` (which preserves Material for MkDocs-style syntax such as admonitions, tabs, and `<<tenant()>>` template macros). Tasks are managed with [mise](https://mise.jdx.dev/) — see `mise.toml` for `setup`, `local`, `build`, `check`, and `fmt` tasks. Nais is a platform that simplifies the deployment and management of applications on Kubernetes (but without having in-depth knowledge of Kubernetes), providing tools and best practices for developers to streamline their workflows.
 
 ## How should GitHub Copilot behave in this repository?
 

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -12,15 +12,15 @@ updates:
       actions:
         patterns:
           - "*"
-  - package-ecosystem: "pip" # poetry / pyproject
-    directory: "/"
+  - package-ecosystem: "npm" # svdoc (SvelteKit + Bun)
+    directory: "/svdoc"
     schedule:
       interval: "weekly"
       time: "09:00"
       day: "monday"
     cooldown:
       default-days: 7
     groups:
-      pip:
+      bun:
         patterns:
           - "*"
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -8,25 +8,14 @@ jobs:
         with:
           fetch-depth: 0 # required for git date plugin
 
-      - name: Install poetry
-        run: pipx install poetry
-
-      - name: Setup Python
-        uses: actions/setup-python@v6
+      - name: Install mise
+        uses: jdx/mise-action@v2
         with:
-          python-version: 3.11
-          architecture: x64
-          cache: poetry
-
-      - name: Install all dependencies
-        run: |
-          poetry sync \
-          --no-interaction \
-          --ansi
+          install: true
+          cache: true
 
       - name: Build documentation
-        run: |
-          ./build.sh nav ssb test-nais ldir atil ci-nais dev-nais tenant
+        run: mise run build nav ssb test-nais ldir atil ci-nais dev-nais
 
       - name: Upload generated doc artifact
         uses: actions/upload-artifact@v6

diff --git a/.gitignore b/.gitignore
@@ -20,3 +20,5 @@ site/
 
 __pycache__/
 .direnv/
+
+/out/
diff --git a/.tool-versions b/.tool-versions
diff --git a/Makefile b/Makefile
diff --git a/README.md b/README.md
@@ -46,32 +46,45 @@ Start with `@research-agent` to gather context, hand off to `@technical-writer`
 
 ## Local development
 
-## 1. Install Poetry
+The documentation site lives in [`svdoc/`](./svdoc) and is built with SvelteKit + Bun. Tasks are managed with [mise](https://mise.jdx.dev/).
+
+### 1. Install mise
+
+Follow the [mise installation guide](https://mise.jdx.dev/getting-started.html). All other tools (such as Bun) are pinned in [`mise.toml`](./mise.toml) and installed automatically.
+
+### 2. Install dependencies
 
 ```bash
-asdf plugin add poetry
-asdf install poetry latest
+mise run setup
 ```
 
-## 2. Install dependencies
+### 3. Serve the documentation locally
 
 ```bash
-make install
+mise run local
 ```
-## 3. Serve the documentation locally
+
+This installs dependencies (if needed) and starts the dev server.
+
+### 3a. Serve a tenant-specific version of the documentation
 
 ```bash
-make local
+TENANT=nav NOT_TENANT=not-nav mise run local:dev
 ```
 
-## 3a. Serve a tenant-specific version of the documentation
+### 4. Build the documentation
+
+Build one or more tenant-specific versions into `out/<tenant>/`:
 
 ```bash
-TENANT=nav make local
+mise run build nav nav test-nais
 ```
 
-## 3b. Do a clean build of the documentation
+### Checks and formatting
 
 ```bash
-make clean-build
+mise run check              # run lint + svelte-check
+mise run check:lint         # prettier + eslint
+mise run check:svelte-check # svelte-check only
+mise run fmt                # format with prettier
 ```
diff --git a/build.sh b/build.sh
diff --git a/custom_theme_overrides/404.html b/custom_theme_overrides/404.html
diff --git a/custom_theme_overrides/main.html b/custom_theme_overrides/main.html
diff --git a/docs/.pages b/docs/.pages
@@ -5,12 +5,12 @@ nav:
 - "": ""
 - workloads
 - build
-- auth
+- Auth: auth
 - observability
-- persistence
+- Persistence: persistence
 - Other services: services
 - "": ""
-- operate
+- Operate: operate
 - "": ""
 - tags.md
 - ...
diff --git a/docs/README.md b/docs/README.md
@@ -5,12 +5,6 @@ hide:
   - footer
   - toc
 ---
-<!-- This hides the edit button on the start page -->
-<style>
-  .md-content__button {
-    display: none;
-  }
-</style>
 
 # :wave: **Welcome to the Nais developer documentation!**
 

diff --git a/docs/auth/README.md b/docs/auth/README.md
@@ -40,9 +40,9 @@ See the different scenarios below to identify which service(s) you need for your
 
 Depending on who your users are, you can use the following services to log them in:
 
-:person_standing: Log in _employees_ :octicons-arrow-right-24: [Entra ID]
+:standing_person: Log in _employees_ :octicons-arrow-right-24: [Entra ID]
 
-:person_standing: Log in _citizens_ :octicons-arrow-right-24: [ID-porten]
+:standing_person: Log in _citizens_ :octicons-arrow-right-24: [ID-porten]
 
 ## Validating inbound requests
 
@@ -63,9 +63,9 @@ graph TD
 
 The graph above can also be described as:
 
-:material-server::person_standing: Validate requests from _internal_ application acting on behalf of _employee_ :octicons-arrow-right-24: [Entra ID]
+:material-server::standing_person: Validate requests from _internal_ application acting on behalf of _employee_ :octicons-arrow-right-24: [Entra ID]
 
-:material-server::person_standing: Validate requests from _internal_ application acting on behalf of _citizen_:octicons-arrow-right-24: [TokenX]
+:material-server::standing_person: Validate requests from _internal_ application acting on behalf of _citizen_:octicons-arrow-right-24: [TokenX]
 
 :material-server: Validate requests from _internal_ application :octicons-arrow-right-24: [Entra ID]
 
@@ -87,9 +87,9 @@ graph TD
 
 The graph above can also be described as:
 
-:material-server::person_standing: Make requests to _internal_ API on behalf of _employee_ :octicons-arrow-right-24: [Entra ID]
+:material-server::standing_person: Make requests to _internal_ API on behalf of _employee_ :octicons-arrow-right-24: [Entra ID]
 
-:material-server::person_standing: Make requests to _internal_ API on behalf of _citizen_ :octicons-arrow-right-24: [TokenX]
+:material-server::standing_person: Make requests to _internal_ API on behalf of _citizen_ :octicons-arrow-right-24: [TokenX]
 
 :material-server: Make requests to _internal_ API :octicons-arrow-right-24: [Entra ID]
 

diff --git a/docs/auth/how-to/login.md b/docs/auth/how-to/login.md
@@ -62,7 +62,7 @@ Before you begin, ensure that you have:
     :   The client secret for your application.
 
 4. Optionally, add additional environment variables to the secret to configure the login proxy further.
-See the [Wonderwall configuration reference :octicons-link-external-16:](https://github.com/nais/wonderwall/blob/master/docs/configuration.md) for all available options.
+See the [Wonderwall configuration reference](https://github.com/nais/wonderwall/blob/master/docs/configuration.md) for all available options.
 
 ## Configure your application
 

diff --git a/docs/explanations/under-the-hood.md b/docs/explanations/under-the-hood.md
@@ -10,9 +10,9 @@ In this explanation, we will go through some of the underlying technologies we u
 
 ### Runtime implementation
 
-Each _environment_ is its own [Kubernetes :octicons-link-external-16:](https://kubernetes.io) cluster using [Google Kubernetes Engine (GKE) :octicons-link-external-16:](https://cloud.google.com/kubernetes-engine?hl=en).
+Each _environment_ is its own [Kubernetes](https://kubernetes.io) cluster using [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine?hl=en).
 
-Inside each environment, every team has their own [namespace :octicons-link-external-16:](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).
+Inside each environment, every team has their own [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).
 
 A namespace can contain one or more [workloads](../workloads/README.md).
 Only members of the team have access to the namespace and its resources.
@@ -33,13 +33,13 @@ In the example above, the team has an application and a job running in the `dev`
 
 All workloads are deployed in a team namespace.
 
-Every workload is isolated from _all_ other workloads with [Kubernetes network policies :octicons-link-external-16:](https://kubernetes.io/docs/concepts/services-networking/network-policies/).
+Every workload is isolated from _all_ other workloads with [Kubernetes network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/).
 
 Access is denied by default, unless [explicitly allowed](../workloads/explanations/zero-trust.md).
 
 ## Google Cloud Platform (GCP) resources
 
-Each team has a dedicated [GCP project :octicons-link-external-16:](https://cloud.google.com/resource-manager/docs/creating-managing-projects) for _each_ environment.
+Each team has a dedicated [GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) for _each_ environment.
 
 When your workload requests resources e.g. a bucket, it will be provisioned in the team's project for the matching environment.
 

diff --git a/docs/observability/.pages b/docs/observability/.pages
@@ -2,4 +2,6 @@ nav:
 - README.md
 - 🎯 How-To: how-to
 - 📚 Reference: reference
+- Frontend: frontend
+- Tracing: tracing
 - ...
diff --git a/docs/persistence/.pages b/docs/persistence/.pages
@@ -1,4 +1,6 @@
 nav:
 - README.md
 - 💡 Explanations: explanations
+- BigQuery: bigquery
+- CloudSQL: cloudsql
 - ...
diff --git a/docs/persistence/opensearch/how-to/create.md b/docs/persistence/opensearch/how-to/create.md
@@ -12,7 +12,7 @@ This guide will show you how to create a OpenSearch instance for your team using
 
 ## Steps
 
-1. Open [Nais Console :octicons-link-external-16:](https://console.<<tenant()>>.cloud.nais.io) in your browser
+1. Open [Nais Console](https://console.<<tenant()>>.cloud.nais.io) in your browser
 2. Select your team
 3. Select **OpenSearch** in the sidebar menu
 4. Click the **Create OpenSearch** button

diff --git a/docs/persistence/opensearch/how-to/upgrade-major-version.md b/docs/persistence/opensearch/how-to/upgrade-major-version.md
@@ -28,7 +28,7 @@ Ensure that your workload is compatible with the new major version of OpenSearch
 
 ### 2. Upgrade the OpenSearch instance
 
-1. Open [Nais Console :octicons-link-external-16:](https://console.<<tenant()>>.cloud.nais.io) in your browser
+1. Open [Nais Console](https://console.<<tenant()>>.cloud.nais.io) in your browser
 2. Select your team
 3. Select **OpenSearch** in the sidebar menu
 4. Select the OpenSearch instance you want to upgrade

diff --git a/docs/persistence/valkey/how-to/create.md b/docs/persistence/valkey/how-to/create.md
@@ -12,7 +12,7 @@ This guide will show you how to create a Valkey instance for your team using [Na
 
 ## Steps
 
-1. Open [Nais Console :octicons-link-external-16:](https://console.<<tenant()>>.cloud.nais.io) in your browser
+1. Open [Nais Console](https://console.<<tenant()>>.cloud.nais.io) in your browser
 2. Select your team
 3. Select **Valkey** in the sidebar menu
 4. Click the **Create Valkey** button

diff --git a/docs/services/.pages b/docs/services/.pages
@@ -3,5 +3,6 @@ nav:
 - CDN: cdn
 - config
 - secrets
+- Vulnerabilities: vulnerabilities
 - feature-toggling.md
 - ...
diff --git a/docs/services/secrets/README.md b/docs/services/secrets/README.md
@@ -12,6 +12,7 @@ Secrets are kept separate from the codebase and configuration files that are usu
 There are two types of secrets on the Nais platform:
 
 <div class="grid cards" markdown>
+
 -   :construction_worker: **Platform-provided secrets**
 
     ---
@@ -22,6 +23,7 @@ There are two types of secrets on the Nais platform:
 </div>
 
 <div class="grid cards" markdown>
+
 - :technologist: **User-defined secrets**
 
     ---

diff --git a/docs/services/secrets/how-to/console.md b/docs/services/secrets/how-to/console.md
@@ -12,7 +12,7 @@ This how-to guide shows you how to create and manage a [secret](../README.md) in
 
 ## List secrets
 
-1. Open [Nais console :octicons-link-external-16:](https://console.<<tenant()>>.cloud.nais.io) in your browser
+1. Open [Nais console](https://console.<<tenant()>>.cloud.nais.io) in your browser
 2. Select your team
 3. Select the `Secrets` tab
 

diff --git a/docs/services/secrets/reference/README.md b/docs/services/secrets/reference/README.md
@@ -8,7 +8,7 @@ This is the reference documentation for [secrets](../README.md) on the Nais plat
 
 ## Console
 
-Visit [Nais Console :octicons-link-external-16:](https://console.<<tenant()>>.cloud.nais.io) to find and manage your team's user-defined secrets.
+Visit [Nais Console](https://console.<<tenant()>>.cloud.nais.io) to find and manage your team's user-defined secrets.
 
 ## Workloads
 

diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
@@ -12,10 +12,10 @@ Tutorials are lessons that focuses on _learning by doing_.
 These give you hands-on experience with various parts of Nais, where we carefully guide you each step of the way.
 
 <div class="grid cards" markdown>
--   :octicons-rocket-24:{ .lg .middle } [**Hello Nais**](./hello-nais.md)
+
+-   :rocket: [**Hello Nais**](./hello-nais.md)
 
     ---
-
     Get your first application up and running on Nais.
 
   </div>
diff --git a/docs/workloads/application/how-to/delete.md b/docs/workloads/application/how-to/delete.md
@@ -10,7 +10,7 @@ tags: [application, how-to]
 
 ## Delete your application
 
-1. Open [Nais console :octicons-link-external-16:](https://console.<<tenant()>>.cloud.nais.io) in your browser
+1. Open [Nais console](https://console.<<tenant()>>.cloud.nais.io) in your browser
 2. Select your team
 3. Select the `Apps` tab
 4. Select the application that you want to delete

diff --git a/docs/workloads/job/how-to/delete.md b/docs/workloads/job/how-to/delete.md
@@ -10,7 +10,7 @@ tags: [job, how-to]
 
 ## Delete your job
 
-1. Open [Nais console :octicons-link-external-16:](https://console.<<tenant()>>.cloud.nais.io) in your browser
+1. Open [Nais console](https://console.<<tenant()>>.cloud.nais.io) in your browser
 2. Select your team
 3. Select the `Job` tab
 4. Select the job that you want to delete