Pandoc en Markdown – Efficiënt een tekst opmaken

Markdown is een populair opmaakformaat. Steeds meer blogsystemen en wiki’s bieden de mogelijkheid in Markdown te werken. Met Pandoc converteer je snel je Markdown-document naar een office-document. Een uitstekende methode om zonder muisklikken goed opgemaakte managementstukken te maken.

Voor het schrijven van tekstdocumenten wordt vaak een office-applicatie gebruikt, bijvoorbeeld LibreOffice. Meestal ben je dan minstens evenveel tijd kwijt aan opmaakacties als aan schrijven. Denk hierbij aan kopjes maken, bullets toevoegen, headers aangeven enzovoort. Eigenlijk is dit zonde van je tijd en had je die tijd beter aan de inhoud van je tekst kunnen besteden. Tekstprocessingsystemen zoals LaTeX kennen dit probleem niet. Je concentreert je bij het schrijven puur op de inhoud. Wanneer je tekst klaar is, laat je dit naar een eindresultaat in een passende stijl converteren. Helaas heb je wel de nodige LaTeXkennis nodig om hier goed en prettig mee te werken. De combinatie van Markdown en Pandoc biedt een goed alternatief. Markdown heb je zo geleerd en Pandoc werkt snel en eenvoudig.

MARKDOWN
Markdown is een eenvoudige opmaaktaal die is ontworpen om het schrijven van webpagina’s zo makkelijk mogelijk te maken. Markdown is een plattetekstformaat. Het is daardoor in elke editor te schrijven. Eén van de uitgangspunten van het ontwerp van Markdown is dat het makkelijk te lezen en makkelijk te schrijven is. Markdown is rond 2004 ontworpen door John Gruber en vervolgens flink verbeterd door Aaron Swartz. Nadat je een tekst in Markdown hebt geschreven, converteer je die naar HTML. Hiervoor heeft Gruber destijds een Perlscript geschreven.

POPULAIR
Markdown is populair en wordt op veel plaatsen gebruikt. Zo zijn de readme-files die je op Github tegenkomt, geschreven in Markdown. Drupal, Blosxom, Movable Type en WordPress hebben plug-ins waardoor je paginateksten in Markdown kunt schrijven. De populariteit van de taal blijkt ook uit het aantal converters die Markdown in HTML omzetten. Naast het oorspronkelijke Perlscript van John Gruber zijn ook Perl-modules ontwikkeld. Ook voor PHP, JavaScript, C, Ruby, Python, Erlang en bijvoorbeeld Lisp bestaan Markdown-modules en/of library’s.

SYNTAXIS
Markdown heeft een eenvoudige syntaxis die je snel onder de knie hebt. Een kopje maak je bijvoorbeeld door aan het begin van de regel een hekje (#) te zetten, gevolgd door een spatie en daarna de tekst van het kopje. Dit wordt straks in HTML een h1-header. Zet je twee hekjes achter elkaar, dan wordt het een h2-header enzovoort. Een paragraaf maak je door een lege regel, gevolgd door een blok tekst, gevolgd door een lege regel. Na conversie komt het blok tekst in HTML tussen <p> en </p> te staan. Een regeleinde maak je door de regel te laten eindigen met twee spaties. Dit wordt in HTML een <br>.

BULLETS
Opsommingtekens (bullets) maak je door aan het begin van de regel een sterretje te zetten, gevolgd door een spatie, gevolgd door tekst. Op de volgende regel zet je weer een sterretje, spatie en tekst. Op deze wijze krijg je een rijtje bullets. In plaats van een sterretje kun je ook een minteken of een plusteken gebruiken. Doe dit wel consequent; wanneer je op de ene regel een sterretje gebruikt en op de volgende een minteken, loop je de kans dat je conversietool het niet meer goed snapt. Een genummerde lijst maak je door de regel te beginnen met een cijfer, gevolgd door een punt, gevolgd door een spatie:

1. Eerste item
2. Tweede item
2. Derde item
2. Vierde item

Je kunt bullets en genummerde lijsten nesten door de binnenste groep eerst met vier spaties of een tab te laten beginnen.

BLOCKQUOTES
Een blockquote maak je door de regels van het blockquote te laten beginnen met een groter-dan-teken, gevolgd door een spatie, dus net als dat je dat in een e-mailbericht zou doen:

> Dit wordt een
> blockquote.

Dingen cursief of vet maken doe je door ze tussen enkele sterretjes of dubbele sterretjes te zetten. In plaats van sterretjes mag je ook underscores gebruiken. Dus *dit wordt cursief* en _dit ook_, **dit wordt vet**.

HYPERLINKS
Hyperlinks in Markdown bestaan uit twee delen: het tekstlabel van de link (de meestal in blauw weergegeven tekst die je op de HTML-pagina ziet) en de URL waar de browser heen moet springen wanneer je op het tekstlabel klikt. In Markdown maak je een hyperlink door eerst het tekstlabel tussen vierkante haken te plaatsen, direct gevolgd door de URL tussen ronde haken:

[Link naar HUB](http:/ www.hub.nl)

Sommige converters laten ook andere methoden toe, die ook meer op de in e-mail gebruikte conventies lijken, bijvoorbeeld door in tekst de referentie [1] neer te zetten, en verderop hier een legenda bij te maken:

[1]: http://www.hub.nl

Lees hiervoor de documentatie van je converter. Het opnemen van een plaatje in je toekomstige HTML-document doe je door direct voor de hyperlink naar de bron van het plaatje een uitroepteken te zetten:


PROGRAMMACODE
Wil je programmacode in je tekst opnemen, dan kan dat op twee manieren. Je kunt tekst tussen backticks (`) opnemen, dus: `dit is code`. De andere manier is de regel te laten beginnen met vier spaties of een tab. Op deze laatste manier kun je eenvoudig codeblokken in je tekst opnemen. Een horizontale streep (<hr> in HTML) maak je door een regel op te nemen die uit drie of meer mintekentjes bestaat. In plaats van mintekens kun je ook sterretjes of underscores gebruiken.

GOED LEESBAAR
Zoals je hierboven hebt gezien, is in Markdown opgemaakte tekst prima leesbaar. Ook is het niet ingewikkeld om te leren. Je kunt Markdown met elke willekeurige tekst-editor schrijven. Daarnaast zijn er hulpmiddelen die het bewerken van Markdown ondersteunen. Voor Vim is bijvoorbeeld een plug-in beschikbaar die voor de goede syntax-highlighting zorgt en automatisch de folding van hoofdstukken voor zijn rekening neemt. Emacs doet daar natuurlijk niet voor onder en heeft een speciale Markdown-mode. Ook vermeldenswaardig zijn online editors zoals Dillinger en EpicEditor. Voor de Chrome-browser is een Markdownextensie beschikbaar. De meeste converters laten gemengd gebruik van Markdown en HTML toe. Je kunt dan bijvoorbeeld het grootste deel van je webpagina in Markdown schrijven en bepaalde stukken – waar je meer controle over het eindresultaat wilt hebben of die minder goed in Markdown zijn uit te voeren – direct in HTML schrijven. Markdown is een prettige methode om vlot de inhoud voor een webpagina te redigeren. Ook kun je je scripts eenvoudig output in Markdown laten maken. Met Pandoc voegen we aan Markdown een hele nieuwe dimensie toe.

PANDOC
Pandoc is gemaakt door John Mac- Farlane en geschreven in Haskell. Het is een open source-conversietool die tekstbestanden naar een ander formaat omzet. Het kan met verschillende input-formaten overweg, zoals Markdown, LaTeX, DocBook en HTML. Pandoc kan deze formaten omzetten in een groot aantal output-formaten waaronder (X)HTML, Microsoft Word docx, OpenOffice odt, EPUB, DocBook, GNU Texinfo, groff manpages, LaTeX, Markdown en Mediawiki markup. Je kunt Pandoc dus gebruiken om van een Markdown-document een odt-document te maken. Je doet dit met de opdrachtregel:

pandoc <input document>
-o <output document>

Bijvoorbeeld:

pandoc bestand.markdown
-o bestand.odt

De kopjes die je in Markdown met één of meer hekjes hebt aangemaakt, worden in het odtdocument nu headers met een overeenkomstig niveau. Wanneer je bijvoorbeeld in het gegenereerde odt-document met LibreOffice een veld voor een automatische inhoudsopgave toevoegt, dan worden de in Markdown opgegeven kopjes netjes herkend en in de inhoudsopgave opgenomen.

TABELLEN
Tabellen maak je ook in platte tekst. Een tabel maak je met behulp van tekstkolommen met een vaste breedte. Een tabel begint en eindigt met een lege regel. Ook wanneer je tabel aan het einde van het document zit, is een lege regel onder de tabel noodzakelijk. De kop van de tabel bestaat uit een regel met kolomkopjes en een regel met mintekens. Neem steeds net zoveel mintekens op als de kolom breed moet zijn. Dan een spatie, en weer een rij mintekens ter breedte van de volgende kolom. De uitlijning van de kopjes boven de mintekens bepaalt of in de tabel straks de kolom links, rechts of gecentreerd wordt uitgelijnd. Onder de regel met de mintekens maak je regels met de inhoud van de kolommen. Houd hierbij de breedte van de kolommen intact, dus laat elk veld precies onder het linker minnetje van de kolomkop beginnen. Voor het uitlijnen van de tekstkolommen kun je in Vim gebruikmaken van de handige plug-in Tabular; in Emacs kun je een hoop met org-mode doen.

VERSIEBEHEER
Markdown is platte tekst. Hierdoor kunnen de verschillende teksttools die je Linux-systeem bevat, er goed mee overweg. Zo kun je makkelijk met diff het verschil tussen twee versies bekijken. Tevens kun je je favoriete versiebeheersysteem gebruiken voor het beheer van je Markdown-bestanden.

OFFICE-DOCUMENTEN
Wanneer je de volgende keer dus weer een beleidsdocument voor het management moet maken, pak je je favoriete editor en schrijf je het in Markdown. Vervolgens knikker je dat door Pandoc heen om er een odt van te maken. Deze open je in LibreOffice en dan zet je nog even de puntjes op de i. Je kunt bijvoorbeeld nog even een inhoudsopgave laten genereren en een footer onderaan de bladzijde opnemen. Niemand die zal merken dat je document zonder een muisklik tot stand is gekomen.