Markdown werd in 2004 gecreëerd door John Gruber met één enkel, elegant doel: schrijf platte tekst die natuurlijk leest, en converteer die vervolgens naar schone HTML. Twee decennia later is het overal — GitHub README-bestanden, beschrijvingen van pull-requests, Slack-berichten, Notion-documenten, blogberichten, AI-chatresponsen. Het is een van die tools die je elke dag zult gebruiken voor de rest van je carrière, of je er nu bewust aan denkt of niet.
Wat Markdown Eigenlijk Is
Markdown is platte tekst met een lichtgewicht, leesbare syntaxis erbovenop. Een # aan het begin van een regel wordt een <h1>. Een woord omwikkelen met **dubbele asterisken** maakt het vet. Backticks produceren inline code. De centrale ontwerpfilosofie is dat Markdown-broncode leesbaar moet zijn zoals hij is — zelfs voordat hij wordt gerenderd. Als je ooit een e-mail hebt geschreven met *asterisken rond nadruk* of koppeltekens hebt gebruikt voor een opsomming, schreef je al iets wat sterk lijkt op Markdown.
Hier is een snel voor-en-na. De Markdown aan de linkerkant produceert de HTML aan de rechterkant:
## Getting Started
Install the package with **npm**:
`npm install my-library`
Then import it in your project — see the [docs](https://example.com) for details.<h2>Getting Started</h2>
<p>Install the package with <strong>npm</strong>:</p>
<p><code>npm install my-library</code></p>
<p>Then import it in your project — see the <a href="https://example.com">docs</a> for details.</p>Jij schrijft de bovenste helft; een Markdown-processor produceert de onderste helft. Die vertaalstap is onzichtbaar zodra het in je editor of CI-pipeline zit.
Basissyntaxis — Het Deel Dat Elke Variant Deelt
Welke Markdown-variant je ook gebruikt, deze bouwstenen werken overal:
- Koppen —
# H1,## H2,### H3(tot zes niveaus) - Vet en cursief —
**vet**,*cursief*,***beide*** - Links —
[linktekst](https://url.com) - Afbeeldingen —
 - Inline code —
`backtick`omsluit een fragment; drie backticks openen een omheind codeblok - Blokcitaten — begin een regel met
> - Ongeordende lijsten — regels die beginnen met
-of* - Geordende lijsten — regels die beginnen met
1.,2., enz. - Horizontale lijn — drie of meer koppeltekens:
---
Hier is een realistisch README-fragment dat al het bovenstaande samen gebruikt:
# json-transform
> A zero-dependency library for transforming JSON structures.
## Installation
```bash
npm install json-transform
```
## Usage
```js
import { transform } from 'json-transform';
const result = transform(input, schema);
```
## Features
- **Fast** — processes 10k objects/sec on average hardware
- *Typed* — ships with full TypeScript definitions
- Zero runtime dependencies
See the [full documentation](https://json-transform.dev/docs) for advanced options.
---
MIT LicenseHet Variantenprobleem — CommonMark, GFM en Anderen
Hier is het addertje: "Markdown" is niet één ding. Gruber's originele specificatie uit 2004 was bewust losjes, wat leidde tot jaren van incompatibele implementaties. Verschillende parsers verwerkte randgevallen — geneste lijsten, lege regels in blokcitaten, prioriteit tussen nadruk en links — op verschillende manieren. Hetzelfde bronbestand werd anders gerenderd in verschillende tools.
CommonMark (gelanceerd in 2014) loste dit op. Een groep ontwikkelaars — inclusief mensen van GitHub, Stack Overflow en Reddit — schreef een rigoureuze, ondubbelzinnige specificatie die elk randgeval dekte met een testsuite van 652 voorbeelden. De meeste moderne tools gebruiken nu CommonMark als basis.
GitHub breidde CommonMark vervolgens uit met eigen toevoegingen en publiceerde GitHub Flavored Markdown (GFM). GFM is wat je schrijft in GitHub README's, issues en pull-requests. Veel andere tools hebben GFM-extensies ook overgenomen, maar niet allemaal — dus wat op GitHub wordt gerenderd, wordt mogelijk niet op dezelfde manier weergegeven in je statische sitegenerator of notitie-app. Weten welke variant je tool ondersteunt, bespaart veel hoofdkrabben.
GitHub Flavored Markdown Extensies
GFM voegt vijf functies toe bovenop CommonMark die je constant zult gebruiken op GitHub en elke tool die de GFM-superset ondersteunt:
Tabellen — pipe-gescheiden kolommen met een scheidingsrij van koppeltekens:
| Method | Returns | Mutates? |
|---------|---------------|----------|
| map() | new array | No |
| filter()| new array | No |
| sort() | same array | Yes |Takenlijsten — selectievakjes in issues en pull-requests:
- [x] Write unit tests
- [x] Update CHANGELOG
- [ ] Add migration guide
- [ ] Tag releaseDoorgestreepte tekst — tekst omwikkelen met dubbele tildes:
~~deprecated API~~ — use `newMethod()` insteadOmheinde codeblokken met taalhinten — de taalidentificator na de openende backticks activeert syntaxismarkering:
```python
def parse_config(path: str) -> dict:
with open(path) as f:
return json.load(f)
```Autolinks — kale URL's zoals https://example.com worden automatisch klikbaar gemaakt zonder de syntaxis [tekst](url). Dit is handig in issueopmerkingen, maar kan verrassend zijn als je een URL plakt die je niet gelinkt wilt hebben.
Waar Je Markdown in de Praktijk Zult Gebruiken
Markdown duikt op in meer plaatsen dan de meeste ontwikkelaars verwachten wanneer ze het voor het eerst tegenkomen:
- GitHub en GitLab — README-bestanden, issues, beschrijvingen van pull-requests, wiki's en zelfs commitberichtbodies. Elke repository die je aanraakt zal minimaal een README.md hebben.
- Statische sitegenerators — Jekyll, Hugo, Eleventy, Astro en Next.js accepteren allemaal Markdown-inhoudsbestanden. Je schrijft berichten in
.md-bestanden en de generator converteert ze tijdens de build naar HTML-pagina's. - Documentatietools — MkDocs, Docusaurus en GitBook zijn volledig gebouwd rond Markdown-broncode. Open-sourcebibliotheken gebruiken bijna universeel een van deze.
- Notitie-apps — Obsidian, Notion, Bear en Typora gebruiken allemaal Markdown als hun eigen formaat (met variërende extensies). Je notities zijn draagbare platte tekstbestanden, geen eigen database.
- CMS-platforms — Ghost gebruikt Markdown van nature. Contentful en Strapi ondersteunen beide Markdown-velden. Headless CMS-opstellingen slaan lange inhoud doorgaans op als Markdown-strings.
- AI-tools — ChatGPT en Claude produceren beide standaard Markdown. Codefragmenten, vette termen en opsommingen in AI-reacties zijn Markdown — de chat-UI rendert ze, maar de onderliggende tekst is
**vet**en```python.
Markdown vs HTML — Wanneer Welke te Gebruiken
Markdown converteert naar HTML, maar kan niet alles uitdrukken wat HTML kan. Er is geen equivalent voor <div class="card">, data-*-attributen of aria-*-attributen. Voor eenvoudige proza-inhoud — documentatie, README's, blogberichten, changelogs — is Markdown sneller om te schrijven en veel leesbaarder in zijn ruwe vorm. Voor complexe UI-componenten, aangepaste indelingen of toegankelijkheidsannotaties die specifieke attributen vereisen, heb je HTML nodig.
Het goede nieuws: de meeste Markdown-processors laten ruwe HTML inline toe. Je kunt de twee mengen. Als je een <figure> met een <figcaption> nodig hebt, of een <details>-openbaarmakingswidget, schrijf dan gewoon de HTML direct in je .md-bestand. De processor geeft het ongewijzigd door. Gebruik dit ontsnappingsluik spaarzaam — als meer dan een derde van je bestand ruwe HTML is, kun je net zo goed rechtstreeks HTML schrijven en onze HTML Formatter gebruiken om het schoon te houden.
- Gebruik Markdown voor: documentatie, README's, changelogs, blogberichten, kennisbankinartikelen, API-beschrijvingsvelden
- Gebruik HTML voor: nauwkeurige indeling, aangepaste componenten, formulieren, elementen die specifieke attributen vereisen
- Meng beide wanneer: voornamelijk proza-inhoud met een handvol structurele uitzonderingen (een responsieve tabel, een video-embed)
Afsluiting
Markdown is bedrieglijk eenvoudig — het lijkt maar een handvol leestekensregels, maar het ondersteunt documentatie voor vrijwel elk groot open-sourceproject. De basissyntaxis begrijpen duurt ongeveer tien minuten. De variantverschillen begrijpen (CommonMark vs GFM vs wat je SSG ook gebruikt) is wat ontwikkelaars die af en toe met hun documentatietooling worstelen scheidt van degenen die dat niet doen.
De gezaghebbende referenties: CommonMark voor de gestandaardiseerde specificatie, GitHub Flavored Markdown voor de GitHub-extensies, en Markdown Guide voor een praktische spiekbriefjesreferentie. Voor dagelijks schrijven laat onze Markdown Preview je direct gerenderde uitvoer zien, en de Markdown Formatter houdt je bronbestanden consistent.