Deze documentatie wordt actief uitgebreid — kom regelmatig terug.

Export Documentation to Word

This guide explains how to convert the markdown documentation to Microsoft Word (DOCX) format, styled with the CTN/DIL Word template in word-template/.

This is an authoring/offline utility, not part of the website build. The live site is built with Astro (npm run build); Word export is a separate, on-demand step you run locally when you need .docx deliverables.

Overview

The export walks every markdown file under docs/ and produces a professionally formatted Word document per file, including:

CTN/DIL logo and branding from the template
A colophon page (document metadata) taken from the template
Heading hierarchy (H1–H4) mapped to the template’s styles
Tables with bold headers
Bullet/numbered lists
Code elements in monospace (Courier New)
Mermaid diagrams rendered to PNG (requires mermaid-cli — see below)

ℹ️ The docs/arc42 content is synced from the CNCL-BDI source repo. Run npm run sync-arc42 before exporting if you want the Word output to reflect the latest arc42 docs. See How To: Update Arc42 Documentation.

Prerequisites

Node.js ≥ 22.12.0 (the repo standard; required anyway for the Astro build)
Terminal window
```
node --version
```

Pandoc 3.x — the core markdown → DOCX converter

pandoc --version          # macOS: brew install pandoc

Python 3 with python-docx — used to merge the template colophon/header
Terminal window
```
pip3 install --break-system-packages python-docx
```
NPM dependencies (installs gray-matter, used to read frontmatter)
Terminal window
```
npm install
```
(Optional) Mermaid CLI — only needed to render Mermaid diagrams as images. The export downloads it on demand via npx, but that pulls a headless Chromium (large/slow on first run). To avoid the per-run download, add it once:
Terminal window
```
npm install --save-dev @mermaid-js/mermaid-cli
```
Without it, the export still completes — diagrams are left as fenced code blocks.

How to Export

# (optional) refresh arc42 from the source repo first
npm run sync-arc42

# convert all markdown under docs/ to Word
npm run export-word
# (identical alias: npm run md-to-docx)

Output location: Export/ (gitignored — not committed)
Output naming: YYYYMMDD-DIL-CTN-<filename>.docx
- Date comes from the lastUpdate frontmatter field (falls back to today’s date)
- Example: 20260531-DIL-CTN-ctn-connector.docx

The export mirrors the docs/ directory structure into Export/. With the current content set (docs/arc42 + docs/how-to + docs/index.md) this is ~50 files and takes a couple of minutes (longer on the first run if Mermaid CLI is downloaded).

Note: the export appends to Export/; it does not wipe it first. Old runs (including content from before any folder was removed) can linger there. Clean it with rm -rf Export/ if you want a fresh set.

The Word template

All styling comes from a single reference document:

word-template/20251111_DIL_CTN_file_name.docx

The export script (scripts/md-to-docx.cjs) passes this file to Pandoc via --reference-doc and then merges in the colophon/header with scripts/merge-docx-template-v3.py. If the template is missing the export aborts with a clear error.

To change the styling (colors, fonts, header, logo, colophon):

Edit word-template/20251111_DIL_CTN_file_name.docx in Word.
Save it (keep the same filename, or update TEMPLATE_FILE in scripts/md-to-docx.cjs).
Re-run npm run export-word — all documents pick up the new styling.

How it works

Two-step conversion per file:

Pandoc converts the markdown to DOCX using the template as --reference-doc, preserving heading styles, tables and lists. Mermaid blocks are pre-rendered to PNG (via mmdc) and embedded as images.
Template merge (merge-docx-template-v3.py) prepends the colophon page, copies the header/logo, replaces the <<title>> placeholder, bolds table headers, and applies Courier New to code-like spans.

Temporary artifacts (*.temp.md, *.temp.docx, .temp-mermaid/) are created during conversion and cleaned up automatically.

Troubleshooting

`Missing script: "export-word"`

You’re on an old checkout. The scripts export-word/md-to-docx are defined in package.json and run scripts/md-to-docx.cjs. Pull the latest and npm install.

`require is not defined` when running the script directly

Run it through npm (npm run export-word) or call the .cjs file (node scripts/md-to-docx.cjs). The script is CommonJS; the package is "type": "module", so a plain .js extension would be treated as ESM and fail.

Pandoc not found

Install Pandoc: brew install pandoc (macOS), then pandoc --version.

`ModuleNotFoundError: No module named 'docx'`

pip3 install --break-system-packages python-docx

Mermaid diagram conversion fails (`could not determine executable to run`)

mermaid-cli isn’t available. Either install it (npm install --save-dev @mermaid-js/mermaid-cli) or ignore it — the export still completes and leaves those diagrams as code blocks (non-fatal).

Word shows “unknown content” / offers to repair on open

Click Yes; Word auto-repairs without data loss. This is a minor DOCX XML quirk.

scripts/md-to-docx.cjs — conversion orchestrator (template path, naming, Pandoc + merge)
scripts/merge-docx-template-v3.py — colophon/header merge and formatting
word-template/20251111_DIL_CTN_file_name.docx — the reference template

Summary

npm run sync-arc42     # (optional) refresh arc42 from CNCL-BDI
npm run export-word    # convert docs/ -> Export/*.docx using the template
open Export/           # view generated documents
rm -rf Export/         # clean output