Ga naar hoofdinhoud

PORTFOLIO-002: Docusaurus als presentatielaag

Status: Geaccepteerd Datum: 2026-05-19

Context​

Documentatie heeft markdown-content in docs/ en (binnenkort) een generator die overlay-pagina's vult ([[PORTFOLIO-001-overlay-geen-mirror]], [[TDS-PORTFOLIO-001-overlay-generator]]). Wat ontbreekt is een presentatielaag: een lezer-vriendelijke site met zoeken, sidebar-navigatie en URLs die je kunt delen — bovendien iets dat als Docker-container op rm-network kan draaien naast de andere apps.

Eisen:

  • Toont alle markdown uit docs/ met sidebar + zoeken
  • Consistent met de portfolio-stack (React, TypeScript)
  • Ondersteunt MDX zodat we later inline React-components kunnen embedden (live MCP-tool-explorer, mini-Geoportaal-iframe, dashboards-stuk)
  • Mermaid-diagrammen renderen (de portfolio-architectuur gebruikt mermaid)
  • Statisch bouwbaar zodat de runtime een nginx-container kan zijn
  • Niet-throwaway: het moet over twee jaar nog een gangbare keuze zijn

Besluit​

Docusaurus 3.x als presentatielaag.

  • Markdown blijft in docs/; Docusaurus serveert dezelfde bestanden.
  • Statische build (build/) wordt door een Caddy-container op rm-network geserveerd.
  • TypeScript-config (docusaurus.config.ts, sidebars.ts).
  • Sidebar wordt auto-generated uit de filesystem-structuur.
  • MDX en mermaid out-of-the-box ingeschakeld.
  • Theming volgt Ruimtemeesters-Platform/brand/RM_Brand_Doc.json: Klein Blue als primary, Pumpkin als CTA, Smart White als background, Raisin Black als typografie. Webfonts: Jost (open-source Futura-alternatief) + Abhaya Libre.

Gevolgen​

Wat de standaard wordt​

  • Eén Node-project in deze repo voor de presentatie; build-output statisch.
  • Configuratiebestanden in repo-root: package.json, docusaurus.config.ts, sidebars.ts, tsconfig.json, src/css/custom.css.
  • Docker-runtime is caddy:2-alpine met de statische output. Geen Node in de runtime-image. Caddy is de portfolio-standaard reverse-proxy/server op deze infrastructuur.
  • URL-plan: documentatie.datameesters.nl (later in te richten via de centrale Caddy-proxy + Workspace-auth-gating, niet nu).

Wat expliciet niet de standaard is​

  • Server-side rendering of een runtime Node-server — niet nodig voor docs.
  • Auth-gating in deze container — dat regelt de proxy / Workspace.
  • Algolia-search in fase 1 — local lunr volstaat tot het volume het rechtvaardigt.
  • Versionering van docs in fase 1 — git-historie volstaat.

Geaccepteerde trade-offs​

  • Een React-bundle voor pure lees-content is overkill, maar geeft ons MDX en consistentie met de rest van het portfolio. Acceptabel.
  • Docusaurus' "category-index uit README"-conventie betekent dat onze huidige folder-READMEs automatisch fungeren als index van hun map — dat past op onze structuur.
  • Wikilinks ([[naam]]) renderen in Docusaurus niet als links. Voor fase 1 accepteren we dat ze als platte tekst verschijnen; later kunnen we een remark-plugin toevoegen die ze resolved.

Overwogen alternatieven​

Astro + Starlight. Lichter en sneller dan Docusaurus, components mengbaar. Afgewezen omdat het minder doc-first defaults heeft (sidebars, search, versies) en de community kleiner is — meer zelf optuigen voor relatief weinig winst.

MkDocs Material. Best-in-class lezer-UX, kleinste build, mooiste defaults. Afgewezen omdat het Python is en daarmee de React-stack-consistentie van het portfolio doorbreekt; we zouden voor docs een aparte technologie binnenhalen die nergens anders draait.

Plain markdown via GitHub. Geen build, geen Docker, nul werk. Afgewezen omdat het de eis "iets dat draait op rm-network" niet vervult en geen zoekfunctie of cross-doc-navigatie biedt.

Gerelateerd​

  • [[PORTFOLIO-001-overlay-geen-mirror]] — content-strategie, orthogonaal aan deze keuze
  • [[TDS-PORTFOLIO-002-docusaurus-docker-opzet]] — de technische uitwerking