minbzk/ls-pub

CONCEPT — Let op: Deze skill is geen officieel product van Logius. De beschrijvingen zijn informatieve samenvattingen — niet de officiële standaarden zelf. De definities op forumstandaardisatie.nl en Logius zijn altijd leidend. Overheidsorganisaties die generatieve AI inzetten dienen te voldoen aan het Overheidsbreed standpunt voor de inzet van generatieve AI. Zie DISCLAIMER.md en onze verantwoording.

Publicatie & Tooling

Agent-instructie: Deze skill is de centrale plek voor publicatie-tooling en kwaliteitschecks van alle Logius standaarden. Gebruik deze skill wanneer de gebruiker een document wil bouwen, valideren (WCAG, markdown lint, link check), publiceren, of een nieuw ReSpec-document wil opzetten. Dit is de ENIGE skill met markdownlint, axe-core en muffet tools.

Versiemodel van standaarden

De publicatie-tooling ondersteunt het versiemodel van Logius-standaarden via de specStatus configuratiewaarde in ReSpec:

| specStatus | Betekenis | Publicatiekanaal | |-----------|-----------|-----------------| | WV | Werkversie (draft) | logius-standaarden.github.io | | CV | Consultatieversie | logius-standaarden.github.io/Openbare-Consultaties/ (automatisch op consultatie/* branches) | | VV | Versie ter vaststelling | gitdocumentatie.logius.nl | | DEF | Vastgestelde versie | gitdocumentatie.logius.nl |

Repositories

| Repository | Beschrijving | Licentie | Publicatie | |-----------|-------------|--------|-----------| | publicatie | Centrale publicatie-repo: alle vastgestelde standaarden | CC-BY-4.0 | gitdocumentatie.logius.nl (geen directory listing) | | Publicatie-Preview | Preview-omgeving voor documenten in ontwikkeling | CC-BY-4.0 | Lees online | | respec | Logius fork van W3C ReSpec documentatie-tool | W3C Software License | - | | ReSpec-template | Basis template voor nieuwe ReSpec documenten | CC-BY-4.0 | Lees online | | ReSpec-template-Logius | Logius-specifiek ReSpec template met huisstijl | CC0-1.0 | Lees online | | Openbare-Consultaties | Gepubliceerde consultatieversies (CV) | CC-BY-4.0 | Lees online | | Automatisering | Herbruikbare GitHub Actions workflows | Niet gespecificeerd | - | | automatisering-test | Testomgeving voor de automatiseringsworkflows | W3C Software License | - | | tech-radar | Technologie radar voor Logius standaarden | MIT | Lees online |

ReSpec Documentatie-systeem

ReSpec genereert technische specificaties als HTML en PDF vanuit Markdown. Logius gebruikt een eigen fork met aangepaste huisstijl.

Hoe ReSpec werkt

Het hoofdbestand index.html laadt de ReSpec-engine en verwijst via data-include naar losse Markdown-bestanden per hoofdstuk:

<section data-include-format="markdown" data-include="ch01.md"></section>
<section data-include-format="markdown" data-include="ch02.md"></section>

ReSpec Configuratie (js/config.mjs)

Nieuwe documenten gebruiken ES-module formaat (config.mjs); oudere repos kunnen nog config.js bevatten.

// js/config.mjs (nieuw, aanbevolen formaat)
import { loadRespecWithConfiguration } from
  "https://logius-standaarden.github.io/publicatie/respec/organisation-config.mjs";

loadRespecWithConfiguration({
  useLogo: true,
  useLabel: true,
  license: "cc-by",
  specStatus: "WV",        // WV=Werkversie, CV=Consultatieversie, VV=Versie ter vaststelling, DEF=Vastgestelde versie
  specType: "HR",           // HR=Handreiking, ST=Standaard, PR=Praktijkrichtlijn, IM=Informatiemodel
  pubDomain: "dk",          // Toegestane waarden: api, bomos, dk, fsc, ftv, logboek, notificatieservices
  shortName: "template",    // Moet kebab-case zijn: alleen kleine letters, gescheiden door streepjes
  publishDate: "2023-06-21",
  publishVersion: "0.0.3",
  editors: [{ name: "Logius Standaarden", company: "Logius", companyURL: "https://logius.nl" }],
  authors: [{ name: "Logius Standaarden", company: "Logius", companyURL: "https://logius.nl" }],
  github: "https://github.com/logius-standaarden/ReSpec-template",
});

Let op: Oudere repos gebruiken config.js met var respecConfig = { ... } syntax. Die bevat soms extra velden zoals content, alternateFormats en postProcess die niet in de config.mjs-variant voorkomen.

Directory Structuur

.github/workflows/    # CI/CD workflows (verwijzen naar Automatisering repo)
js/config.mjs         # ReSpec configuratie (of config.js bij oudere repos)
media/                # Afbeeldingen, diagrammen
ch01.md, ch02.md      # Hoofdstukken
abstract.md           # Samenvatting
index.html            # ReSpec entry point

GitHub Actions Workflows (Automatisering repo)

Alle standaarden-repos roepen centrale workflows aan uit de Automatisering repo.

build.yml - Document Generatie

1. Branch-detectie: consultatie/* branches krijgen automatisch specStatus: "cv" (via sed op config.mjs)
2. HTML generatie: npx respec --localhost --src index.html --out ~/static/index.html --haltonwarn
3. PDF generatie via Puppeteer/headless Chrome (met scripts/pdf.js)
4. Cache opslag als GitHub Actions cache

check.yml - Kwaliteitschecks (3 parallelle checks)

1. WCAG check: npx @axe-core/cli http://localhost:8080/index.html --tags wcag2aa (geautomatiseerde check; dekt ~30% van WCAG-criteria, handmatige toetsing blijft nodig). axe-core is een van meerdere tools die gestandaardiseerde W3C ACT Rules implementeren; alternatieven zijn o.a. Alfa (Siteimprove) en QualWeb.
2. Markdown lint: npx markdownlint-cli sections/
3. Link validatie: Muffet valideert alle hyperlinks

publish.yml - Publicatie

Bevat meerdere jobs afhankelijk van de context:

• Release (push naar main/master): publiceert naar de centrale publicatie repo (gitdocumentatie.logius.nl)
• Deploy develop (push naar develop): publiceert naar GitHub Pages van de standaarden-repo zelf
• Preview (pull request): publiceert een preview naar de Publicatie-Preview repo
• Consultatie (consultatie/* branches): publiceert naar de Openbare-Consultaties repo

link-checker.yml - Gepubliceerde Links Controleren

Controleert periodiek of de gepubliceerde versie op gitdocumentatie.logius.nl geen dode links bevat. Stuurt een e-mail bij gevonden fouten.

Calling Workflow Voorbeeld

# .github/workflows/build.yml in een standaarden-repo
name: Build document
on:
  push:
    branches: [main, 'consultatie/*']
  pull_request:
    branches: [main]

jobs:
  build:
    uses: logius-standaarden/Automatisering/.github/workflows/build.yml@main
    with:
      workflow_input_file_names: '["index.html"]'

Nieuw Document Starten

1. Fork het template: Gebruik ReSpec-template-Logius als basis
2. Configureer js/config.mjs: Pas specStatus, specType, pubDomain, shortName, title aan. pubDomain accepteert alleen api, bomos, dk, fsc, ftv, logboek of notificatieservices. shortName moet in kebab-case (alleen kleine letters, gescheiden door streepjes, bijv. rest-api)
3. Schrijf content: Maak hoofdstukken als losse Markdown-bestanden
4. Push naar GitHub: CI/CD bouwt automatisch HTML en PDF

Checks Lokaal Draaien

# ReSpec bouwen naar statische HTML
npx respec --src index.html --out output.html

# WCAG Accessibility check (wcag2aa niveau)
npx @axe-core/cli output.html --tags wcag2aa
# ⚠️ Let op: axe-core checkt automatisch ~30% van de WCAG-criteria.
# Een groene check betekent NIET dat je volledig voldoet aan EN 301 549 / WCAG 2.1 AA.
# Handmatige toetsing op alle 55 succescriteria in WCAG 2.1 AA blijft nodig.
# axe-core implementeert W3C ACT Rules (https://www.w3.org/WAI/standards-guidelines/act/rules/)
# Alternatieven: Alfa (Siteimprove), QualWeb

# Markdown linting
npx markdownlint-cli 'sections/**/*.md'

# Link validatie (start eerst een lokale server)
npx http-server -p 8080 . &
muffet http://localhost:8080/index.html

Foutafhandeling

| Fout | Oorzaak | Oplossing | |------|---------|----------| | ReSpec error: data-include file not found | Markdown-bestand ontbreekt | Controleer data-include verwijzingen | | WCAG violation: Images must have alternate text | Afbeelding zonder alt-tekst | Voeg alt-tekst toe: ![Beschrijving](media/img.svg) | | Geen WCAG violations gevonden | axe-core heeft geen fouten gedetecteerd | Let op: dit betekent niet dat het document volledig toegankelijk is. axe-core test ~30% van de WCAG 2.1 AA criteria. Toets handmatig op alle 55 succescriteria in WCAG 2.1 AA, waaronder toetsenbordnavigatie, leesbare kopstructuur en logische leesvolgorde. | | markdownlint MD013: Line length | Regel te lang | Breek af op ~120 karakters | | muffet: 404 Not Found | Dode link | Verwijder of update de link | | PDF generation failed | Puppeteer crash | Controleer of document valid HTML genereert |

Consultatie Branch Gedrag

Op consultatie/* branches wordt specStatus automatisch overschreven naar "cv". Na merge naar main wordt specStatus uit js/config.mjs gebruikt.

Achtergrondinfo

Zie reference.md voor gedetailleerde info over tech radar, label-updates workflow, en workflow-configuratie. Zie conflicts.md voor bronconflicten en gemaakte keuzes.