MD naar PDF omzetten

Dit is het verschil met elke andere documentomzetting op de site. Een Word-bestand kent zijn paginaformaat, marges en lettertypen; een Markdown-bestand kent niets daarvan, want het formaat legt bewust structuur vast en laat het uiterlijk over aan wat het weergeeft.

Elke beslissing over de pagina — formaat, marges, lettertype, waar een afbreking valt — wordt dus door de omzetter genomen, en geen ervan staat in je bestand. Dat is de ruil die Markdown maakt, meestal een goede: hetzelfde document wordt een webpagina, een presentatie en een PDF zonder herschreven te worden. De kosten komen hier naar boven, want een omzetter die niet weet hoe Markdown te lezen, heeft niets te renderen en valt terug op de tekens zoals ze zijn.

Elk teken van het bestand komt op volgorde op de pagina, in één lettertype. Een regel ## Vereisten wordt gezet als ## Vereisten. Een opsommingsteken met een koppelteken is een regel die met een koppelteken begint. Niets valt weg en niets wordt geïnterpreteerd, want de documentengine achter dit paar leest tekst en heeft nooit een Markdown-filter gekregen.

Wat overblijft is de moeite van preciseren waard. Regelafbrekingen, lege regels en inspringing blijven exact behouden, dus een document waarvan de waarde in de commando’s of de configuratie zit, zet netjes om. Een document waarvan de waarde in de kophiërarchie zit, doet dat niet.

Een Markdown-document met zes diagrammen bevat geen diagrammen. Het bevat zes paden, en de afbeeldingen staan ernaast op schijf of op een server. Dat verrast mensen die voor het eerst omzetten, en het is de meest voorkomende reden dat een PDF met gaten aankomt.

De oplossing is de paden vooraf laten kloppen. Relatieve paden moeten naar bestanden wijzen die echt bij het document horen; absolute webadressen hangen af van een bereikbare server. Zijn de afbeeldingen het punt van het document, dan is dit de stap om goed te doen, niet de omzettingsinstellingen.

Heel veel Markdown-bestanden beginnen met een blok tussen drie koppeltekens met een titel, datum en tags. Statische-site-generators, documentatiebouwers en notitie-apps lezen dat als metadata en verwijderen het voor de rest gerenderd wordt.

Deze omzetting kent die conventie niet en drukt het blok af zoals al het andere, dus de PDF begint met drie koppeltekens en een lijst sleutel-waardeparen voor het document begint. Het blok verwijderen voor het omzetten is de hele oplossing.

De oorspronkelijke Markdown-beschrijving uit 2004 was informeel, CommonMark is de precieze specificatie die de meeste tools volgen, en de pipe-tabellen, taaklijsten, voetnoten en doorhalingen die iedereen gebruikt zijn uitbreidingen erop. Welke een tool implementeert, bepaalt normaal hoe een document eruit komt.

Dat is niet de vraag op deze pagina. Niets hier implementeert een van deze extensies, of de kern zelf, dus een GitHub-tabel en een CommonMark-kop worden identiek behandeld — als regels tekst. Wat je in je editor met syntaxaccentuering uit ziet, is wat de PDF zal bevatten.

Omdat het publiek niet jij bent. Een klant, een advocaat, een commissie of een compliance-medewerker wil een document dat te openen, af te drukken, te ondertekenen en te archiveren is — niet een bestand dat hun machine aanbiedt te openen in een codeeditor.

Een PDF bevriest ook de staat. Een README verandert elke week; een PDF ervan is wat waar was op de dag dat hij ergens bij werd gevoegd, precies wat een review of een contractbijlage nodig heeft. Blijf schrijven in Markdown en exporteer op het moment dat iemand buiten een kopie nodig heeft.

HTML als de bestemming een webpagina of documentatiesite is, want Markdown was ontworpen als steno ervoor en de omzetting lijkt meer op een vertaling dan op een weergave.

DOCX in één specifieke, veelvoorkomende situatie: de ontvanger accepteert alleen een Word-bestand en wil bijgehouden wijzigingen toevoegen. Markdown kent geen reviewproces, dus is DOCX beter voor een ronde commentaar, en PDF voor de versie die af is. Dat doel loopt via dezelfde engine, dus de opmaak komt ook als tekst in het Word-bestand aan — het verschil is dat de reviewer een kop kan repareren en jij dat in een PDF niet kunt.