Udvikling af dokumentationssitet

Dokumentationen ligger samlet i docs-site/src/content/docs/. Dette er den fælles kilde til både projektvejledninger og dokumentation af de centrale scripts. De tidligere separate guides og Confluence-filer er flyttet hertil.

Sitet bruger samme Astro Starlight-versioner, danske navigation og Ecreo-tema som dokumentationssitet i Ecreo.Essentials. Det bygges til statiske HTML-filer med lokal søgning, kodeformatering samt lyst og mørkt tema.

Lokal udvikling

Brug Node.js 22.12 eller nyere og pnpm 10.12.1, som er angivet i package.json. Kommandoerne køres fra det centrale CI/CD-repository:

cd docs-site
pnpm install --frozen-lockfile
pnpm dev

Åbn den lokale URL, som Astro skriver i terminalen. Søgningens fulde indeks dannes ved produktionsbuild, så brug preview til at teste søgning.

Kontrollér og byg

pnpm check
pnpm build
pnpm preview

pnpm check kontrollerer Astro- og TypeScript-konfiguration. pnpm build genererer sitet og søgeindekset i dist/ og kontrollerer lokale links og ankre i de byggede HTML-filer. Et ødelagt lokalt link giver en fejlkode og stopper buildet.

node_modules/, .astro/, dist/ og pnpm-cachen er genererede filer og skal ikke committes.

Hver Markdown-fil i src/content/docs/ bliver en side. Filen starter med frontmatter:

---
title: Min vejledning
description: Hvad udvikleren kan bruge siden til.
---

Brug /opsaetning/ og lignende site-stier til links mellem sider. Opdatér sidebaren i astro.config.mjs, når der tilføjes eller flyttes sider. Filen src/styles/ecreo-theme.css indeholder Ecreo-temaet.

Skriv på dansk. Bevar kommandoer, variabelnavne og API-felter på deres faktiske form. Opdatér dokumentationen i samme ændring, når scripts, templates, konfiguration eller publicering ændrer adfærd.

Changelog

Vedligehold Changelog i src/content/docs/changelog.md, når der sker ændringer i pipeline-adfærd, opsætning eller publicering, som udviklere eller vedligeholdere skal kende. Skriv en kort dansk beskrivelse under ændringens dato, og link til den relevante commit, når den findes. Brug datoer frem for versionsnumre.

Historikken før det første publiceringstag er samlet månedsvis. Brug Git-historikken og publiceringstags som dokumentation; en commitdato er ikke et bevis på tidspunktet for deployment. Angiv det, hvis en ændrings publicering endnu ikke er bekræftet.

Deployment til Azure Static Web Apps

Opret en Azure Static Web App til dette site. Hent deployment-tokenet fra Azure, og opret AZURE_STATIC_WEB_APPS_API_TOKEN som en sikret Bitbucket repository-variabel. Tokenet er specifikt for denne Static Web App og skal ikke kopieres fra Essentials-ressourcen.

Repositoryets pipeline bygger og deployer dokumentationen ved ændringer under docs-site/ eller i bitbucket-pipelines.yml på main. PR-pipelinen kontrollerer og bygger samme indhold uden deployment. Der er også en manuel deploy-documentation-pipeline til første publicering eller genudgivelse.

Pipeline-steppet bruger Node 22, pnpm 10.12.1 og Azure Static Web Apps CLI 2.0.9. Det færdigbyggede dist/ uploades med miljøet production. Der kræves ingen server eller SPA-fallback til at vise siderne.

Når deployment-tokenet mangler, fejler deployment med en forklaring. Det påvirker ikke de allerede publicerede CI-script-blobs. Opret tokenet, og kør deploy-documentation igen, når Azure-ressourcen er klar.

Når sitets endelige URL er kendt, kan site tilføjes i astro.config.mjs, og README kan linke direkte til det publicerede site. Lokal udvikling og statisk build kræver ingen produktions-URL.

Dokumentationsmigreringen

docs-site/DOCS_COVERAGE.md beskriver, hvor emnerne fra de tidligere guides findes. Rapporten omfatter README, begge setup-guides, using/developing-guides og de danske Confluence-sider. Den skelner mellem migreret indhold, rettede forældede eksempler og vejledning, der kun gjaldt manuel Confluence-import.

De eksisterende Confluence-sider er historiske kopier og er ikke slettet af denne migration. Når det nye site er publiceret, kan de arkiveres eller få et link til det. Fremtidige ændringer skal kun vedligeholdes her i repositoryet.