Documentatie uitbreiden

Deze site is een Astro Starlight-app in apps/docs. Alle inhoud is Markdown; je hebt geen kennis van Astro nodig om een pagina toe te voegen.

Waar wat staat

apps/docs/
├── astro.config.mjs          # titel, sidebar-secties, GitHub-links
├── src/
│   ├── content.config.ts     # koppelt de map hieronder als content-collectie
│   ├── content/docs/         # hier staan alle pagina's
│   │   ├── index.mdx         # de startpagina
│   │   ├── introductie/
│   │   ├── aan-de-slag/
│   │   ├── architectuur/
│   │   ├── beheer/
│   │   ├── besluiten/
│   │   └── bijdragen/
│   └── styles/custom.css     # kleine thema-aanpassingen
└── public/favicon.svg

Een map is een sectie in de sidebar, een bestand is een pagina. De URL volgt het pad: architectuur/datamodel.md wordt /architectuur/datamodel/. Bestandsnamen zijn kleine letters met streepjes, zonder punten.

Een pagina toevoegen

1. Kies de map; zie Waar hoort wat.

2. Maak mijn-onderwerp.md met minimaal een title in de frontmatter:

   ---
   title: Mijn onderwerp
   description: Eén zin die in zoekresultaten en onder de paginakop verschijnt.
   sidebar:
     order: 3
   ---
   
   De eerste alinea zegt in gewone taal waar de pagina over gaat en voor wie hij is.
   
   ## Eerste kop

3. Start pnpm --filter docs run dev en open http://localhost:4322. De pagina staat meteen in de sidebar.

Schrijf geen # Kop bovenaan de tekst: Starlight maakt de H1 uit title. Begin je koppen bij ##; die vormen automatisch de inhoudsopgave rechts.

Frontmatter die je vaker nodig hebt

Veld	Doet
title	Verplicht. Paginakop en tabtitel.
description	Onder de kop, in zoekresultaten en in de meta-tags.
sidebar.order	Volgorde binnen de sectie, oplopend. Pagina’s zonder order komen alfabetisch na de genummerde.
sidebar.label	Kortere naam in de sidebar dan de titel.
sidebar.badge	Bijvoorbeeld { text: "Nieuw", variant: "tip" }.
sidebar.hidden	true verbergt de pagina uit de sidebar; de URL blijft werken.
draft	true houdt de pagina uit de productiebuild; in dev blijft hij zichtbaar.
lastUpdated	Standaard uit git; false verbergt de datum.

De volledige lijst staat in de frontmatter-referentie van Starlight.

Een sectie toevoegen

Maak een nieuwe map onder src/content/docs/ en voeg één blok toe aan de sidebar in astro.config.mjs:

{
  label: "Nieuwe sectie",
  items: [{ autogenerate: { directory: "nieuwe-sectie" } }],
},

Een submap binnen een sectie wordt automatisch een uitklapbare subgroep, met de mapnaam als label. Houd het bij één niveau diep; dieper wordt onoverzichtelijk.

Linken

• Naar een andere pagina: absoluut pad met een slash aan het eind, [Datamodel](/architectuur/datamodel/).
• Naar een kop: voeg het anker toe, [harde regels](/architectuur/overzicht/#harde-regels). Het anker is de kop in kleine letters met streepjes.
• Naar code in de repo: schrijf het pad als inline code, zoals apps/site-template/src/middleware.ts. De lezer vindt het zelf; een GitHub-link veroudert bij elke verplaatsing.
• Rechts op elke pagina staat Bewerk pagina, die naar het bestand op GitHub gaat.

Opmaak

Alles wat in GitHub-Markdown werkt, werkt hier: tabellen, codeblokken met taal (bash, ts, json, sql), citaten, taaklijsten. Daarbovenop:

Asides voor dingen die op moeten vallen:

:::note
Achtergrondinformatie.
:::

:::tip[Eigen titel]
Een handige manier om iets te doen.
:::

:::caution
Hier gaat het vaak mis.
:::

:::danger
Dit vernietigt gegevens.
:::

Diagrammen zijn ASCII in een codeblok, zoals in Architectuur. Dat rendert overal, is te vergelijken in git en heeft geen extra tooling nodig.

Componenten (kaarten, stappen, bestandsbomen, tabs) vragen een .mdx-bestand en een import bovenaan:

import { Steps, FileTree, Card, CardGrid } from "@astrojs/starlight/components";

Voorbeelden staan in index.mdx, aan-de-slag/lokaal-draaien.mdx en aan-de-slag/repo-rondleiding.mdx. Let op: in MDX zijn accolades en punthaken in gewone tekst bijzondere tekens. Zet placeholders zoals {slug} of <domein> altijd in backticks. Twijfel je, kies dan .md.

Afbeeldingen: zet ze in src/assets/ en verwijs relatief, ![Alt-tekst](../../assets/schema.png); Astro optimaliseert ze bij de build. Alt-tekst is verplicht, net als in het CMS.

Waar hoort wat

Vraag van de lezer	Sectie	Toon
Wat is dit en waarom?	Introductie	Uitleg voor iemand zonder voorkennis; leg elke vakterm uit of link naar Begrippen
Hoe kom ik aan de gang?	Aan de slag	Stappen die je kunt volgen, met de commando’s erbij
Hoe zit het in elkaar?	Architectuur	Het waarom achter de code. Levende documenten: bij afwijking wint de code en werk je het document bij
Hoe beheer of deploy ik?	Beheer en deploy	Runbooks: exacte stappen, exacte commando’s, wat er misgaat
Wat is er besloten en gebeurd?	Taken en beslissingen	Logboeken en plannen met een datum; niet herschrijven, wel aanvullen
Hoe werk ik aan de docs?	Over deze documentatie	Deze pagina

Twijfel? Een pagina die begint met “we hebben gekozen voor” is een beslissing; een pagina die begint met “zo werkt het” is architectuur; een pagina die begint met “draai” is beheer.

Schrijfafspraken

• Nederlands proza, Engelse namen. Tabelnamen, variabelen en commando’s blijven zoals ze in de code staan.
• Dateer feiten die kunnen veranderen: “op 7 september 2026 geverifieerd”, “peildatum 8 september 2026”. Een gedateerde uitspraak veroudert eerlijk; een ongedateerde lijkt altijd waar.
• Bewijs boven bewering. Schrijf wat er is getest en hoe, niet alleen dat het werkt.
• Korte alinea’s, koppen om te scannen. De inhoudsopgave rechts is voor veel lezers de eerste stop.
• Eén onderwerp per pagina. Wordt een pagina langer dan een scherm of vijf, splits dan.
• Verwijs, herhaal niet. Staat iets al in Architectuur, link ernaar.

Onderhoud hoort bij de wijziging

Verandert het gedrag van het systeem, dan wordt de documentatie in dezelfde pull request bijgewerkt. AGENTS.md in de repo-root zegt AI-agents hetzelfde en wijst naar de belangrijkste pagina’s hier. Verhuis of hernoem je een pagina, zoek dan op het oude pad in de hele repo (AGENTS.md, .cursor/rules/, commentaar in code) en werk de verwijzingen bij.

Controleren voordat je pusht

pnpm --filter docs run build      # faalt op ontbrekende title of kapotte frontmatter
pnpm --filter docs run typecheck  # astro check

De build maakt ook de zoekindex (Pagefind). Zoeken werkt daarom alleen in de gebouwde site: pnpm --filter docs run build && pnpm --filter docs run preview. In de dev-server meldt het zoekveld dat zoeken niet beschikbaar is; dat is normaal.

Deployen

De build levert een statische site in apps/docs/dist/, zonder server. Die is overal te hosten: Coolify met een statische build pack, Cloudflare Pages, GitHub Pages. Dit is nog niet ingericht. Zodra er een publieke URL is, zet die als site in astro.config.mjs, zodat Starlight ook een sitemap genereert.