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:

Repositories

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-check op pull requests (sinds september 2026): een directe PR van develop naar main/master of andersom wordt geweigerd; maak een tussenbranch. Een PR naar main/master vereist specStatus: "DEF" of "VV" in js/config.mjs, een PR naar develop vereist "WV". Zo kan een werkversie niet per ongeluk als vastgestelde versie worden gepubliceerd.
2. Branch-detectie: consultatie/* branches krijgen automatisch specStatus: "cv" (via sed op config.mjs)
3. HTML generatie: npx respec --localhost --src index.html --out ~/static/index.html --haltonwarn
4. PDF generatie via Puppeteer/headless Chrome (met scripts/pdf.js)
5. 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

Consultatie Branch Gedrag

Op consultatie/* branches wordt specStatus automatisch overschreven naar "cv". Na merge naar main wordt specStatus uit js/config.mjs gebruikt. Sinds september 2026 controleert build.yml bij een PR naar main/master dat js/config.mjs op "DEF" of "VV" staat en bij een PR naar develop dat die op "WV" staat.

Achtergrondinfo

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