Documentatie: mermaid-fence ontbreekt in FILE_FORMAT.md §14 en visueel-editor-limiet in KNOWN_LIMITATIONS.md

brenno commented

2026-09-02 13:26:05 +00:00

Owner

Probleem

Drie documentatiegaten rond de Mermaid-fence in documenten:

1. FILE_FORMAT.md §14 noemt ```mermaid nergens

Er hoort een paragraaf bij die vastlegt:

De fence is draagbare Markdown (gewoon een code-fence met mermaid als taal).
OciDeck tekent hem in lezer, voorvertoning, Pagina's, PDF en HTML-export.
In de visuele editor toont hij (nog) als codeblok — zie het afzonderlijke issue voor de MermaidEmbedBuilder.
Renderregels:
- htmlLabels uit, dus regeleinden met <br/> en geen HTML in labels.
- Tekening op ware grootte, dus breedte binnen de tekstkolom houden (642 px bij A4 met 20 mm marges).
- <style> wordt ingelijnd; <marker>, <filter> en <foreignObject> worden door de allow-list weggehaald, met pijlpunten als gebakken polygonen.
- %%{init}-directives worden gehonoreerd behalve de secure-sleutels.

2. FILE_FORMAT.md §14.11 mist de tijdlijntabel-zin

In §14.11 hoort de zin dat de tijdlijntabel de chronologievorm is die in alle weergaven werkt (lezer, voorvertoning, Pagina's, PDF, HTML-export en visuele editor).

3. KNOWN_LIMITATIONS.md mist de regel over de visuele editor

KNOWN_LIMITATIONS.md mist de regel dat de visuele editor Mermaid (en chart-fences en blokformules) als codeblok toont in plaats van als gerenderde kaart.

Referenties

docs/FILE_FORMAT.md §14 en §14.11
docs/KNOWN_LIMITATIONS.md
docs/design/DOCUMENT_MODE.md §4.3 (de belofte die de documentatie zou moeten dekken)

## Probleem Drie documentatiegaten rond de Mermaid-fence in documenten: ### 1. FILE_FORMAT.md §14 noemt ```mermaid nergens Er hoort een paragraaf bij die vastlegt: - De fence is draagbare Markdown (gewoon een code-fence met `mermaid` als taal). - OciDeck tekent hem in lezer, voorvertoning, Pagina's, PDF en HTML-export. - In de visuele editor toont hij (nog) als codeblok — zie het afzonderlijke issue voor de `MermaidEmbedBuilder`. - **Renderregels:** - `htmlLabels` uit, dus regeleinden met `<br/>` en geen HTML in labels. - Tekening op ware grootte, dus breedte binnen de tekstkolom houden (642 px bij A4 met 20 mm marges). - `<style>` wordt ingelijnd; `<marker>`, `<filter>` en `<foreignObject>` worden door de allow-list weggehaald, met pijlpunten als gebakken polygonen. - `%%{init}`-directives worden gehonoreerd behalve de secure-sleutels. ### 2. FILE_FORMAT.md §14.11 mist de tijdlijntabel-zin In §14.11 hoort de zin dat de tijdlijntabel de chronologievorm is die in **alle** weergaven werkt (lezer, voorvertoning, Pagina's, PDF, HTML-export en visuele editor). ### 3. KNOWN_LIMITATIONS.md mist de regel over de visuele editor `KNOWN_LIMITATIONS.md` mist de regel dat de visuele editor Mermaid (en chart-fences en blokformules) als codeblok toont in plaats van als gerenderde kaart. ## Referenties - `docs/FILE_FORMAT.md` §14 en §14.11 - `docs/KNOWN_LIMITATIONS.md` - `docs/design/DOCUMENT_MODE.md` §4.3 (de belofte die de documentatie zou moeten dekken)

brenno added the

docs

in-progress

labels

2026-09-02 15:21:48 +00:00

brenno commented

2026-09-02 15:21:48 +00:00

Author

Owner

Opgepakt. Tak: docs/mermaid-file-format, gestapeld op fix/mermaid-embed-visual-editor (#1920) — punt 3 hangt af van die reparatie: zodra mermaid wél als kaart in de visuele editor komt, gaat de KNOWN_LIMITATIONS-regel alleen nog over chart-fences en blokformules.

De renderregels uit de issuetekst zijn tegen de code getoetst voordat ze de documentatie in gaan: htmlLabels uit, securityLevel strict en de zes onaantastbare secure-sleutels staan in services/mermaid_config.dart; de allow-list in utils/sanitize_svg.dart laat style, marker, filter en foreignObject inderdaad vallen. Eén punt uit de issuetekst klopt na #1921 niet meer: 'tekening op ware grootte' geldt nog voor de lezer, maar Pagina's en PDF schalen nu juist naar de kolom.

Opgepakt. Tak: docs/mermaid-file-format, gestapeld op fix/mermaid-embed-visual-editor (#1920) — punt 3 hangt af van die reparatie: zodra mermaid wél als kaart in de visuele editor komt, gaat de KNOWN_LIMITATIONS-regel alleen nog over chart-fences en blokformules. De renderregels uit de issuetekst zijn tegen de code getoetst voordat ze de documentatie in gaan: htmlLabels uit, securityLevel strict en de zes onaantastbare secure-sleutels staan in services/mermaid_config.dart; de allow-list in utils/sanitize_svg.dart laat style, marker, filter en foreignObject inderdaad vallen. Eén punt uit de issuetekst klopt na #1921 niet meer: 'tekening op ware grootte' geldt nog voor de lezer, maar Pagina's en PDF schalen nu juist naar de kolom.