Wat is Markdown? Syntaxis, CommonMark en GFM

Denk aan de README van een softwareproject, de lijsten met koppen in een notitie-app of de woorden die je in een chatapp met sterretjes vet maakt. Achter al die dingen zit hetzelfde idee: Markdown. Markdown is een lichte opmaaktaal waarmee je koppen, lijsten, links en tabellen aangeeft door een paar eenvoudige symbolen aan platte tekst toe te voegen. Het bestand blijft in elke teksteditor leesbaar, maar je kunt het wanneer je wilt omzetten in een nette HTML-pagina, een Word-document of een PDF. Dit artikel vertelt hoe Markdown is ontstaan, wat de basissyntaxis is, waarin CommonMark en GitHub Flavored Markdown verschillen en waar je op let bij het converteren van MD-bestanden.

Wat is Markdown?

Markdown is zowel een set schrijfconventies als de gangbare naam voor tools die tekst in die conventies naar HTML omzetten. Bestanden krijgen meestal de extensie .md of .markdown. Volgens bedenker John Gruber is leesbaarheid het allesoverheersende ontwerpdoel: een Markdown-document moet zo als platte tekst te publiceren zijn, zonder dat het eruitziet alsof het vol tags of opmaakinstructies staat. Waar HTML <strong>belangrijk</strong> nodig heeft, gebruikt Markdown **belangrijk**, en zelfs de ruwe versie leest natuurlijk.

Een korte geschiedenis

John Gruber bedacht Markdown in 2004, met Aaron Swartz als klankbord voor zijn ideeën. De syntaxis putte uit conventies uit e-mail in platte tekst (sterretjes voor nadruk, streepjes voor lijsten) en uit eerdere opmaaktalen zoals setext en Textile. Versie 1.0.1 van Markdown.pl, het Perl-script dat Gruber op zijn site Daring Fireball publiceerde, is gedateerd op 17 december 2004.

Grubers beschrijving was echter een uitleg aan de hand van voorbeelden en geen formele specificatie. Bij dubbelzinnige gevallen (geneste lijsten, ingesprongen codeblokken, gemengde HTML) maakte elke implementatie haar eigen keuzes, en dezelfde tekst begon in verschillende tools verschillende uitvoer op te leveren. Daarop volgden twee grote antwoorden:

• CommonMark (2014): een specificatie onder leiding van John MacFarlane die Markdown eenduidig definieert en met honderden voorbeelden testbaar maakt. De eerste versies verschenen in het najaar van 2014; de huidige versie is 0.31.2, gedateerd 28 januari 2024. De specificatie is nog niet tot 1.0 verklaard.
• GitHub Flavored Markdown (GFM, 2017): de formele specificatie van GitHub, gebouwd op CommonMark. Ze voegt uitbreidingen toe zoals tabellen, takenlijsten, doorhalen, uitgebreide autolinks en, om veiligheidsredenen, het filteren van bepaalde ruwe HTML-tags. De laatst gepubliceerde specificatie is 0.29-gfm, gedateerd 6 april 2019.

Markdown kreeg ook erkenning in de infrastructuur van internet: RFC 7763, gepubliceerd in maart 2016, registreerde het mediatype (MIME-type) text/markdown met een optionele parameter variant die aangeeft welke Markdown-variant de auteur bedoelde.

Belangrijke Markdown-varianten

Naast CommonMark en GFM zijn er nog andere wijdverbreide varianten. RFC 7764, gelijktijdig met RFC 7763 gepubliceerd, registreerde er een aantal en gaf richtlijnen voor het gebruik:

• Markdown Extra: een vroege uitbreiding die voetnoten, definitielijsten en tabellen toevoegde.
• MultiMarkdown: een variant voor academisch schrijven, met metadata, citaten en kruisverwijzingen.
• Pandoc Markdown: de variant van de converter Pandoc, met veel uitbreidingen voor het schrijven van boeken en artikelen.

Een praktische vuistregel: gebruikt je document alleen koppen, lijsten, links, code en eenvoudige tabellen, dan ziet het er bijna overal hetzelfde uit. Leun je op voetnoten, definitielijsten of speciale bloktypen, controleer dan welke variant de doelomgeving ondersteunt.

Basissyntaxis

Het deel van Markdown dat je dagelijks nodig hebt, leer je in een paar minuten:

# Kop van niveau één
## Kop van niveau twee
Deze alinea bevat **vet**, *cursief* en `code`.
- Opsomming
- Tweede item
  - Ingesprongen subitem
1. Genummerde lijst
2. Tweede stap
[Linktekst](https://example.com)
![Beschrijving van de afbeelding](afbeelding.png)
> Citaatblok
```
Codeblok over meerdere regels
```

Tabellen en takenlijsten, toegevoegd door GFM, zien er zo uit:

| Formaat | Extensie |
|---------|----------|
| Markdown | .md |
| Platte tekst | .txt |
- [x] Concept schrijven
- [ ] Nalezen

Alinea's worden gescheiden door lege regels. Eén enkele regelovergang telt in de meeste implementaties als deel van dezelfde alinea; wil je een harde regelovergang, eindig de regel dan met twee spaties. Je kunt ook rechtstreeks HTML in Markdown schrijven. CommonMark staat dat toe, al blokkeren omgevingen zoals GFM bepaalde tags om veiligheidsredenen.

Waar wordt Markdown gebruikt?

• Softwareontwikkeling: README's, changelogs en bijdragegidsen, plus issues en opmerkingen bij codereviews op platforms zoals GitHub en GitLab.
• Technische documentatie: statische sitegenerators die websites bouwen uit Markdown-bestanden.
• Notities maken: veel notitie-apps bewaren of exporteren notities als Markdown.
• Chat- en communityplatforms: platforms zoals Reddit en Discord gebruiken varianten van Markdown.
• Schrijven en publiceren: HTML, PDF, DOCX en EPUB maken uit één Markdown-bron met tools zoals Pandoc.
• AI-tools: AI-assistenten in chatvorm maken hun antwoorden vaak op in Markdown.

Sterke en zwakke punten

Met welke programma's open je Markdown?

Omdat Markdown platte tekst is, opent het in elke teksteditor, ook in Kladblok en TextEdit. Voor een opgemaakte voorvertoning kun je de ingebouwde Markdown-preview van Visual Studio Code gebruiken of speciale editors zoals Obsidian en Typora. GitHub en GitLab geven .md-bestanden in repositories automatisch opgemaakt weer. Word daarentegen opent Markdown niet als opgemaakte tekst, dus dan moet je het bestand eerst converteren.

Veelvoorkomende problemen en oplossingen

Een lijst of kop wordt niet weergegeven

CommonMark vereist een spatie na het kopteken: ## Kop, niet ##Kop. Een lijst direct na een alinea heeft ook vaak een lege regel ertussen nodig om goed te worden weergegeven.

Regels lopen in elkaar over

Eén regelovergang splitst geen alinea. Laat een lege regel staan voor een nieuwe alinea, of eindig de regel met twee spaties om binnen een alinea naar een nieuwe regel te gaan.

Een tabel werkt op het ene platform wel en op het andere niet

Tabellen horen niet bij Grubers oorspronkelijke Markdown of bij de kern van CommonMark; ze komen uit uitbreidingen zoals GFM. Controleer welke variant het doelplatform ondersteunt.

Een alinea die met een getal begint, wordt een genummerde lijst

Een regel als "2024. was een druk jaar" begint met cijfers en een punt en kan daarom als lijst worden gelezen. Zet een backslash voor de punt (2024\.) om dat te voorkomen.

Tips voor het converteren van Markdown-bestanden

Bij onze converter worden Markdown-bestanden naar onze server geüpload en binnen 30 minuten verwijderd. Voor het inlezen gebruiken we de bibliotheek Markdig met CommonMark en uitbreidingen in GitHub-stijl (tabellen, takenlijsten, voetnoten, autolinks).

• Markdown naar PDF en Markdown naar Word behouden koppen, lijsten, codeblokken, citaatblokken en tabellen met randen. Selectievakjes uit takenlijsten worden omgezet in de tekens ☑ en ☐, zodat ze in Word en PDF zichtbaar blijven. Tekst wordt standaard gezet in een schreeflettertype van 12 pt, en codeblokken in een lettertype met vaste breedte.
• Markdown naar HTML maakt van een README een zelfstandige webpagina met een opgegeven tekencodering.
• De andere kant op leveren Word naar Markdown, HTML naar Markdown en PDF naar Markdown Markdown op die compatibel is met GitHub: koppen, vette en cursieve tekst, lijsten, tabellen, links, codeblokken en citaatblokken blijven behouden; lettertypen, kleuren en pagina-opmaak vallen weg. In tabellen zonder koprij wordt de eerste rij de koprij, omdat GFM-tabellen er een vereisen. Gewone alinea's die met een getal beginnen, zoals "1. Artikel", worden geëscapet zodat ze niet per ongeluk lijsten worden. Het bestand wordt opgeslagen als UTF-8 zonder BOM.

Veelgestelde vragen

Hoe open ik een MD-bestand?

Elke teksteditor opent het. Wil je het opgemaakt zien, gebruik dan de preview van Visual Studio Code of een Markdown-editor; wil je het in Word lezen, converteer het dan naar DOCX.

Wat is het verschil tussen CommonMark en GitHub Flavored Markdown?

CommonMark legt de basissyntaxis van Markdown vast met precieze regels. GFM is een uitbreiding daarvan die bovenop CommonMark extra's toevoegt, zoals tabellen, takenlijsten, doorhalen en uitgebreide autolinks.

Kan ik tabellen maken in Markdown?

Ja, met uitbreidingen zoals GFM schrijf je eenvoudige tabellen met verticale strepen en streepjes. Voor complexe structuren zoals samengevoegde cellen gebruik je een HTML-tabel of maak je het document in Word.

Wat is het verschil tussen Markdown en HTML?

Markdown is een eenvoudiger schrijfformaat dat bedoeld is om naar HTML te worden omgezet. Het kan niet alles uitdrukken wat HTML kan, maar de ruwe vorm is veel beter leesbaar. Waar nodig kun je nog steeds HTML in Markdown schrijven.

Heeft Markdown een officiële norm?

Grubers oorspronkelijke beschrijving is geen formele specificatie. De meest geaccepteerde precieze definitie is vandaag CommonMark, en het mediatype text/markdown werd in maart 2016 geregistreerd met RFC 7763.

Bronnen

• John Gruber, Daring Fireball: Markdown
• CommonMark Spec (versiegeschiedenis)
• GitHub Flavored Markdown Spec
• IETF RFC 7763: The text/markdown Media Type (maart 2016)
• IETF RFC 7764: Guidance on Markdown
• Wikipedia: Markdown (geschiedenis, secundaire bron)
• Markdig: een CommonMark-conforme Markdown-processor voor .NET