Markdown omzetten naar publicatieklaar‑formaat

Markdown is de lingua franca geworden voor ontwikkelaars, schrijvers en open‑source‑gemeenschappen. De platte‑tekst‑syntaxis is makkelijk te schrijven, versie‑te controleren en weer te geven op verschillende platformen. Toch verwachten de meeste lezers nog steeds gepolijste PDF’s, responsieve HTML‑pagina’s of EPUB‑e‑books. Het omzetten van Markdown naar deze downstream‑formaten zonder koppen, tabellen, code‑blokken of metadata te verliezen kan verrassend lastig zijn. Deze gids loopt een reproduceerbare workflow door die balans biedt tussen getrouwheid, prestaties en privacy.

Het bronmateriaal begrijpen

Beschouw het Markdown‑bestand vóór elke conversie als een brondocument in plaats van een eindproduct. Identificeer de elementen die speciale behandeling vereisen:

  • Front‑matter‑metadata (titel, auteur, datum, tags). In veel statische‑site‑generatoren verschijnt dit als YAML begrensd door ---. Houd het behouden omdat downstream‑formaten het vaak nodig hebben voor omslagpagina’s of ingebedde metadata.
  • Code‑omslagen met taalkennmerken. Syntax‑highlighting moet de conversie overleven, vooral voor technische boeken.
  • Tabellen, voetnoten en definitielijsten. Niet alle doel‑formaten ondersteunen ze natively; je moet ze mogelijk mappen naar HTML <table> of PDF‑tabelstructuren.
  • Afbeeldingen en assets die met relatieve paden worden aangeduid. Een conversiepijplijn moet die paden oplossen en optioneel de binaire data insluiten.
  • Interne links (bijv. [Sectie](#sectie)) en document‑overstijgende referenties. Bij het genereren van één PDF of EPUB moeten deze omgezet worden naar functionele bladwijzers of hyperlinks.

Door deze aspecten vroeg te inventariseren, vermijd je later onverwachte verrassingen in de pijplijn.

De juiste conversie‑engine kiezen

Er zijn drie brede families van converters voor Markdown:

  1. Pandoc‑gebaseerde pijplijnen – Pandoc is een universele documentconverter die Markdown kan lezen en PDF, HTML, EPUB, DOCX en nog veel meer formaten kan genereren. Het blinkt uit in het verwerken van citaties, voetnoten en aangepaste sjablonen.
  2. Statische‑site‑generatoren (SSG’s) – Tools zoals Hugo, Jekyll of MkDocs renderen Markdown naar HTML met themasystemen. Ze zijn ideaal wanneer je een volledige website nodig hebt, maar kunnen ook gecombineerd worden met headless‑print‑tools.
  3. Web‑gebaseerde diensten – Platforms zoals convertise.app bieden een REST‑endpoint dat een Markdown‑bestand accepteert en het gewenste uitvoerformaat terugstuurt. Ze zijn handig voor eenmalige conversies zonder software te installeren.

Voor een herhaalbare, privacy‑eerste workflow wordt een lokale Pandoc‑installatie aanbevolen. Deze draait volledig op de machine van de gebruiker, zonder sporen achter te laten op een externe server.

De omgeving voorbereiden

  1. Installeer Pandoc (nieuwste stabiele versie) en een LaTeX‑distributie (bijv. TinyTeX) als je PDF‑s wilt genereren.
  2. Zet een virtuele omgeving op (Python venv of Node nvm) om hulpprogramma’s geïsoleerd te houden.
  3. Verzamel assets – kopieer alle gerefereerde afbeeldingen, PDF‑s en lettertypebestanden naar één map. Dit maakt pad‑resolutie triviaal voor de converter.
  4. Maak een metadata‑bestand – ontbreekt de front‑matter in je Markdown, schrijf dan een klein metadata.yaml met title, author, date en eventuele andere velden die je wilt insluiten.
---
title: "Effectieve Open‑Source Documentatie"
author: "Jane Doe"
date: "2026-05-10"
keywords: [markdown, documentation, publishing]
---

Je kunt dit blok aan elk bronbestand vooraf laten gaan of via --metadata-file aan Pandoc doorgeven.

Naar PDF converteren

Stap 1: Een LaTeX‑sjabloon kiezen

Pandoc gebruikt LaTeX onder de motorkap voor PDF‑output. Een goed ontworpen sjabloon regelt marges, kop‑/voettekststijlen, lettertypen en de weergave van code‑blokken. Het officiële eisvogel‑sjabloon is een populair startpunt omdat het:

  • Syntax‑geaccentueerde code‑blokken ondersteunt via het listings‑pakket.
  • Een klikbare inhoudsopgave genereert.
  • Metadata insluit in het XMP‑pakket van de PDF, wat nuttig is voor digitale bibliotheken.

Download het sjabloon en plaats het naast je assets.

Stap 2: Pandoc aansturen met de juiste vlaggen

pandoc main.md \
  --metadata-file=metadata.yaml \
  --template=eisvogel.tex \
  --toc \
  --highlight-style=pygments \
  --pdf-engine=xelatex \
  -V mainfont="Libre Baskerville" \
  -V monofont="Fira Code" \
  -o output.pdf

Belangrijke opties uitgelegd:

  • --toc maakt een automatische inhoudsopgave.
  • -V mainfont en -V monofont zorgen dat de PDF de gewenste visuele identiteit behoudt.
  • --highlight-style garandeert consistente kleurenschema’s voor code‑omslagen.

Stap 3: Het resultaat verifiëren

Open de PDF en controleer:

  • Alle koppen verschijnen in de inhoudsopgave met correcte paginanummers.
  • Code‑blokken zijn leesbaar en behouden taal‑specifieke kleuren.
  • Afbeeldingen zijn ingesloten (niet gelinkt) en proportioneel geschaald.
  • Metadata (auteur, titel) verschijnt in de documenteigenschappen (Bestand → Eigenschappen → Beschrijving).

Ontbreekt er iets, pas dan het sjabloon aan of voeg Pandoc‑filters toe (bijv. pandoc-citeproc voor citaties).

Naar HTML converteren

HTML is de native output voor de meeste Markdown‑engines, maar voor publicatieklaar gebruik heb je schone markup nodig zonder de extra klassen die SSG’s injecteren.

Stap 1: Een minimalistisch CSS‑framework kiezen

Een lichtgewicht stylesheet zoals Pure.css of een eigen style.css houdt de pagina snel en biedt slimme defaults voor tabellen, blockquotes en code. Sla het CSS‑bestand op in dezelfde map als de gegenereerde HTML.

Stap 2: De HTML met Pandoc genereren

pandoc main.md \
  --metadata-file=metadata.yaml \
  --standalone \
  --toc \
  --css=style.css \
  --highlight-style=pygments \
  -o output.html

De --standalone‑vlag omsluit de body in een volledig HTML‑document, terwijl --toc een navigatie‑zijbalk injecteert die gestyled kan worden als vaste positie.

Stap 3: Toegankelijkheid verbeteren

  • Voeg lang="nl" toe aan de <html>‑tag (Pandoc doet dit automatisch als je lang=nl instelt).
  • Zorg dat alle afbeeldingen een alt‑attribuut hebben; als je Markdown dit wegliet, voeg ze dan toe via een Pandoc‑filter of door de bron te bewerken.
  • Controleer of kopniveaus hiërarchisch zijn (h1 → h2 → h3).

Stap 4: Testen in browsers

Open output.html in Chrome, Firefox en Edge. Controleer of code‑blokken scrollbaar zijn op smalle viewports en of de TOC elegant inklapt. Gebruik Lighthouse (ingebouwd in Chrome DevTools) om te bevestigen dat de pagina goed scoort op performance en toegankelijkheid.

Naar EPUB (e‑Book) converteren

EPUB is in feite een ZIP‑archief van XHTML, CSS en metadata. Pandoc abstraheert de complexiteit en levert een nette pakket.

Stap 1: De EPUB‑metadata afstemmen

Gebruik Pandoc’s --epub-metadata‑vlag om ID, uitgever en taalinformatie in te sluiten. Maak een simpel epub-metadata.xml:

<?xml version="1.0" encoding="UTF-8"?>
<dc:metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:title>Effectieve Open‑Source Documentatie</dc:title>
  <dc:creator>Jane Doe</dc:creator>
  <dc:language>nl</dc:language>
  <dc:identifier id="bookid" opf:scheme="ISBN">978-3-16-148410-0</dc:identifier>
  <dc:publisher>Zelf‑gepubliceerd</dc:publisher>
</dc:metadata>

Stap 2: Pandoc met EPUB‑opties aansturen

pandoc main.md \
  --metadata-file=metadata.yaml \
  --epub-metadata=epub-metadata.xml \
  --toc \
  --css=style.css \
  --highlight-style=pygments \
  -o book.epub

De inhoudsopgave wordt het navigatiebestand van het e‑book, en de CSS zorgt voor consistente opmaak op alle apparaten.

Stap 3: De EPUB valideren

Gebruik epubcheck (een open‑source validator) om gebroken links, missende afbeeldingen of slecht gevormde XHTML te detecteren. Voer uit:

java -jar epubcheck.jar book.epub

Los alle gerapporteerde problemen op voordat je het bestand verspreidt of uploadt naar platforms zoals Kindle Direct Publishing.

Asset‑insluiting en pad‑resolutie behandelen

Markdown verwijst vaak naar afbeeldingen met relatieve paden (![](images/logo.png)). Tijdens conversie moet je die assets insluiten in plaats van externe links te laten staan, vooral voor PDF en EPUB.

  • Pandoc biedt de optie --resource-path om de converter te laten weten waar hij assets moet vinden.
  • De vlag --extract-media=./media kopieert gekoppelde media naar een media‑map en herschrijft de markup zodat die naar die kopieën wijst.
  • Voor PDF zorgt de optie --pdf-engine-opt=--shell-escape (bij gebruik van LaTeX) ervoor dat de engine externe bestanden kan includen.

Wil je een enkel‑bestand uitvoer (bijv. een zelf‑bevatte HTML), gebruik dan een naverwerkingsstap met pandoc --self-contained of een extern tool als wget --convert-links.

Code‑highlighting behouden over formaten heen

Consistente syntax‑highlighting is cruciaal voor documentatie gericht op ontwikkelaars.

  • Pandoc ondersteunt meerdere highlight‑stijlen (pygments, kate, tango). Kies er één die er zowel in PDF als HTML goed uitziet.
  • Voor PDF vertaalt Pandoc de highlighting naar LaTeX listings of minted. minted vereist de vlag --pdf-engine-opt=-shell-escape en het Python‑pakket pygments.
  • Voor EPUB wordt de highlighting gerenderd als inline CSS‑spans (<span class="hlkwd">). Zorg dat je CSS‑bestand de bijbehorende style‑regels bevat.

Wil je een eigen kleurenschema, genereer dan een stijlbestand met pygmentize -S <style> -f html -a .code en neem het op in je CSS.

De workflow automatiseren met een Makefile

Het telkens handmatig uitvoeren van dezelfde commandoregel‑stappen voor elk formaat is fout‑gevoelig. Een eenvoudige Makefile waarborgt reproduceerbaarheid:

SOURCES = main.md metadata.yaml
ASSETS  = $(wildcard images/*)

PDF    = output.pdf
HTML   = output.html
EPUB   = book.epub

all: $(PDF) $(HTML) $(EPUB)

$(PDF): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --template=eisvogel.tex \
	  --toc \
	  --highlight-style=pygments \
	  --pdf-engine=xelatex \
	  -V mainfont="Libre Baskerville" \
	  -V monofont="Fira Code" \
	  -o $@

$(HTML): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --standalone \
	  --toc \
	  --css=style.css \
	  --highlight-style=pygments \
	  -o $@

$(EPUB): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --epub-metadata=epub-metadata.xml \
	  --toc \
	  --css=style.css \
	  --highlight-style=pygments \
	  -o $@

clean:
	rm -f $(PDF) $(HTML) $(EPUB)

Voer make uit om nu alle drie de uitvoerformaten met één commando te produceren, zodat elk formaat uit exact dezelfde bronbestanden ontstaat.

Wanneer een cloud‑service zoals convertise.app te gebruiken

In sommige situaties heb je geen lokale LaTeX‑installatie of moet je een bestand op een tijdelijke machine converteren. Een online converter kan het zware werk doen terwijl privacy behouden blijft als de service de data in‑memory verwerkt en geen bestanden langdurig opslaat. Een beknopt voorbeeld van een POST‑verzoek naar een generieke conversie‑endpoint:

POST https://convertise.app/api/convert
Content-Type: multipart/form-data

--- 
Content-Disposition: form-data; name="file"; filename="main.md"
Content-Type: text/markdown

<Markdown-inhoud>
---
Content-Disposition: form-data; name="target"

pdf
---

Het antwoord levert de geconverteerde PDF als binaire stream. Deze aanpak werkt prima voor eenmalige taken, maar voor reproduceerbare publicatie‑pijplijnen blijft de lokale Pandoc‑oplossing het meest transparant en audit‑baar.

Testen op getrouwheid over formaten heen

Na conversie voer je een reeks geautomatiseerde controles uit:

  1. Checksum‑vergelijking – genereer een SHA‑256‑hash van de bron‑Markdown en bewaar deze naast de outputbestanden. Zo bewijs je dat de bron niet gewijzigd is tussen builds.
  2. Link‑validatie – gebruik pandoc --filter pandoc-citeproc om te verzekeren dat elke interne referentie wordt opgelost.
  3. Afbeeldings‑rasterisatie‑test – open de PDF en EPUB in aparte viewers en controleer dat afbeeldingen niet onder de gewenste DPI worden gesampled (meestal 300 dpi voor druk, 72 dpi voor scherm).
  4. Toegankelijkheids‑audit – tools zoals pdfaPilot voor PDF of axe-core voor HTML detecteren ontbrekende alt‑tekst of een onjuiste heading‑volgorde.
  5. Spell‑check – draai aspell of hunspell op de gegenereerde HTML of PDF (geëxtraheerd via pdftotext) om transcriptiefouten die filters introduceren op te vangen.

Deze checks in een CI‑pipeline (GitHub Actions, GitLab CI) zorgen ervoor dat elke commit een geverifieerde set publiceerbare assets oplevert.

Samenvatting van de workflow

  1. Bron‑Markdown en assets verzamelen. Voeg front‑matter toe indien nodig.
  2. Conversie‑engine selecteren (Pandoc wordt aanbevolen voor maximale controle).
  3. Sjablonen en CSS configureren voor elk doelformaat.
  4. Conversie‑commando’s uitvoeren – PDF via LaTeX, HTML met een minimale stylesheet, EPUB met metadata.
  5. De outputs valideren – checksum, linkintegriteit, toegankelijkheid en visuele inspectie.
  6. Automatiseren met een Makefile of CI om het proces herhaalbaar te houden.

Met dit recept krijg je consistente, publicatieklaar documenten uit een enkele Markdown‑bron, of je nu een ontwikkelaars‑handleiding, een academisch handboek of een e‑book wilt publiceren.

De hier beschreven technieken zijn compatibel met privacy‑gerichte diensten zoals convertise.app, die als optioneel on‑demand conversie‑endpoint kunnen dienen wanneer lokale tooling niet beschikbaar is.