Momenteel neem ik geen nieuwe klanten aan +31 6 301 963 14 dennis@gouwers.nl
Webdevelopment

Markdown, YAML en JSON: de bestanden achter een snelle website

Bijgewerkt op 10 min leestijd

In dit artikel

Markdown is een manier om tekst op te maken met gewone tekens, zoals een hekje voor een kop en sterretjes voor vet. YAML en JSON zijn formaten voor gegevens: YAML is makkelijk te lezen voor mensen, JSON is strenger en de standaard tussen systemen. Op een statische website staat de inhoud vaak in deze drie soorten bestanden, met bovenaan elk artikel een blokje YAML: de front matter. Ook mijn eigen sites zijn zo opgebouwd: je inhoud staat in gewone tekstbestanden, en die houd ik voor je bij.

Wat is Markdown?

Markdown is een eenvoudige schrijfwijze voor opgemaakte tekst. Je typt gewone tekens, en een programma maakt daar HTML van, de taal waarin webpagina's zijn geschreven. John Gruber bedacht Markdown in 2004 met één hoofddoel: de tekst moet ook zonder omzetting zo goed mogelijk leesbaar zijn.

Zo ziet een stukje Markdown eruit:

## Openingstijden

We zijn **op maandag gesloten**. Kom je voor het eerst?

- Neem je legitimatiebewijs mee
- Kom tien minuten eerder

Lees meer over [onze behandelingen](https://voorbeeld.nl/behandelingen/).

Twee hekjes maken een tussenkop, twee sterretjes maken tekst vet, een streepje begint een opsomming en blokhaken met haakjes maken een link. Ook zonder uitleg kun je dit lezen. Dat is de kracht van Markdown: de tekst blijft tekst.

Je komt Markdown vaker tegen dan je denkt. Veel notitie-apps gebruiken het, en de sterretjes en hekjes die je soms ziet als je een antwoord uit een AI-chatbot kopieert, zijn ook Markdown. Een llms.txt, een bestand dat AI-systemen een overzicht van je site geeft, is ook in Markdown geschreven. Of je site er een nodig heeft, lees je in llms.txt.

De oorspronkelijke beschrijving van Markdown liet details open. Daarom bestaan er varianten, zoals CommonMark, een nauwkeurige beschrijving van hoe Markdown gelezen moet worden, en de variant van GitHub met onder meer tabellen. Welke variant een site gebruikt, bepaalt bijvoorbeeld of een tabel als tabel verschijnt of als een rij streepjes.

Wat is YAML?

YAML is een formaat voor gegevens die mensen moeten kunnen lezen en aanpassen. De naam is een grapje van de makers: YAML Ain't Markup Language, YAML is geen opmaaktaal. Leesbaarheid voor mensen staat in de officiële beschrijving bovenaan.

Je schrijft een naam, een dubbele punt en een waarde. Lijsten maak je met streepjes, en wat bij elkaar hoort, spring je in. Een voorbeeld met verzonnen gegevens:

bedrijf: "Bakkerij De Voorbeeldhoek"
telefoon: "012 345 67 89"  # staat in de footer en op de contactpagina
menu:
  - titel: "Home"
    adres: "/"
  - titel: "Assortiment"
    adres: "/assortiment/"
toonNieuwsbrief: true

Alles na het hekje is een opmerking: een notitie voor mensen, die de computer overslaat. YAML heeft twee strenge regels. Inspringen gaat met spaties, nooit met tabs; de officiële beschrijving verbiedt tabs voor het inspringen. En het inspringen bepaalt wat bij wat hoort. Eén spatie te veel of te weinig en een menu-item hangt onder het verkeerde kopje.

Het verraderlijke is dat zo'n fout niet altijd een foutmelding geeft. Het bestand kan geldig blijven en toch iets anders betekenen dan bedoeld. Dan bouwt de site gewoon, maar staat er een menu-item op de verkeerde plek of ontbreekt een openingstijd.

Er zit nog een valkuil in. Oudere programma's die YAML lezen, zien woorden als yes, no, on en off als ja of nee in plaats van als tekst. Tekst hoort daarom bij twijfel tussen aanhalingstekens, en zeker als er een dubbele punt in staat.

Je vindt YAML vooral in instellingenbestanden en in de front matter boven artikelen, waarover verderop meer.

Wat is JSON?

JSON staat voor JavaScript Object Notation. Het is volgens de officiële standaard, RFC 8259 uit 2017, een licht, tekstgebaseerd formaat om gegevens uit te wisselen, los van welke programmeertaal je gebruikt. Het komt uit JavaScript, maar elke programmeertaal kan het lezen.

Dezelfde gegevens als in het YAML-voorbeeld, nu in JSON:

{
  "bedrijf": "Bakkerij De Voorbeeldhoek",
  "telefoon": "012 345 67 89",
  "menu": [
    { "titel": "Home", "adres": "/" },
    { "titel": "Assortiment", "adres": "/assortiment/" }
  ],
  "toonNieuwsbrief": true
}

JSON is streng. Namen en teksten staan tussen dubbele aanhalingstekens, tussen elk onderdeel staat een komma, accolades vormen een groep en blokhaken een lijst. Opmerkingen kunnen er niet in. Eén vergeten komma en het hele bestand is onleesbaar voor de computer. Dat klinkt lastig, maar het betekent ook dat er nooit twijfel is over wat er staat.

Daarom is JSON de standaardtaal tussen systemen. Vraagt je website gegevens op bij een ander systeem, dan komt het antwoord vrijwel altijd als JSON terug. Hoe zo'n uitwisseling verloopt, staat in wat is een API-koppeling. Ook structured data, de extra informatie waarmee je Google vertelt wat er op een pagina staat, wordt meestal in een vorm van JSON geschreven.

De twee formaten zijn familie: sinds YAML 1.2 is elk geldig JSON-bestand ook geldige YAML.

Markdown, YAML en JSON naast elkaar

Markdown YAML JSON
Waarvoor Lopende tekst met opmaak Gegevens en instellingen die mensen bijhouden Gegevens tussen systemen en in databestanden
Leesbaar voor mensen Heel goed Goed Redelijk
Hoe streng Vergevingsgezind Streng op inspringen Heel streng
Opmerkingen toevoegen Kan, als HTML-opmerking Ja, na een hekje Nee
Bestandsextensie .md .yml of .yaml .json
Voorbeeld op een website Artikel, dienstpagina Front matter, menu, instellingen Openingstijden, API-antwoord, structured data

Op een statische site, waar alle pagina's vooraf worden gebouwd, zie je ze vaak alle drie. De teksten staan in Markdown. Gegevens die op veel plekken terugkomen, zoals adressen of openingstijden, staan in een databestand in YAML of JSON. Bij Eleventy, waarmee ik meestal bouw, komt elk JSON-bestand in de map _data automatisch beschikbaar op elke pagina. Een bestand locaties.json heet in de site dan gewoon 'locaties'. Waarom zo'n vaste plek voor gegevens zoveel scheelt, leg ik uit bij contentmodel.

Front matter: het blokje gegevens boven een artikel

Front matter is een blokje YAML bovenaan een Markdown-bestand, tussen twee regels met drie streepjes. Er staan gegevens in over de pagina zelf. Daaronder volgt de tekst. Eén bestand, twee delen: de gegevens en het verhaal.

Zo ziet dat eruit:

---
title: "Nieuwe openingstijden vanaf januari"
date: "2026-12-01"
description: "Vanaf januari zijn we op zaterdag tot 16.00 uur open."
categorie: "Nieuws"
---

Vanaf januari zijn we op **zaterdag langer open**. Je bent welkom tot 16.00 uur.

De static site generator, het programma dat van je bestanden een website maakt, leest de front matter. De titel komt in het tabblad van de browser en in Google, de datum bepaalt de volgorde in het nieuwsoverzicht en de categorie bepaalt op welke overzichtspagina het bericht verschijnt. Eleventy leest front matter standaard als YAML en kan ook JSON of JavaScript aan.

De artikelen van deze kennisbank werken ook zo. Elk artikel is een Markdown-bestand met bovenaan front matter, met onder meer de titel, de beschrijving voor Google, de categorie en de veelgestelde vragen. Welke velden in de front matter horen, is een keuze die bij je contentmodel hoort. Die keuze gaat jaren mee, want elk sjabloon en elk overzicht op de site leest die velden.

Waarom mensen en AI deze bestanden goed kunnen lezen

Het is gewone tekst. Deze bestanden openen in elk programma dat tekst kan tonen. Er is geen speciale software of inlog nodig, en over twintig jaar zijn ze nog steeds leesbaar.

Elke wijziging is zichtbaar. Staat een site in versiebeheer, dan is per regel te zien wat er is veranderd. Een gewijzigde openingstijd is één regel die rood wordt en één die groen wordt. Hoe zo'n logboek van wijzigingen werkt, beschrijf ik in Git en versiebeheer.

AI kan er goed mee overweg. Deze formaten komen overal op internet voor, dus AI-modellen kennen ze goed. Een codeer-agent, een AI-programma dat rechtstreeks met de projectbestanden werkt, kan alle bestanden doorzoeken, een wijziging overal hetzelfde doorvoeren en laten zien wat hij heeft aangepast.

Fouten vallen meestal op. Omdat YAML en JSON streng zijn, valt een fout meestal al op bij het bouwen van de site, nog voordat een bezoeker hem ziet. In het bestand met bouwafspraken van een project kunnen regels staan zoals 'datums altijd als 2026-11-06' en 'tekst in YAML altijd tussen aanhalingstekens'. Welke afspraken er nog meer in zo'n bestand staan, zie je bij bouwafspraken voor je codeer-agent.

Leesbaar is wel iets anders dan veilig aan te passen. Een tab in plaats van spaties, een vergeten aanhalingsteken of een dubbele punt op de verkeerde plek kan een build laten mislukken, of erger, een pagina stilletjes verkeerd tonen. Daarom werk ik nooit met de hand in een live site. Mijn codeer-agent past de bestanden aan, de site wordt opnieuw gebouwd en pas als ik het resultaat heb gecontroleerd, gaat het live. Jij hoeft alleen door te geven wat er moet veranderen.

Waarom inhoud in bestanden makkelijk te verhuizen is

Staat je inhoud in Markdown, YAML en JSON, dan is verhuizen vooral kopiëren. Er is geen database-export nodig en geen plugin die alles omzet. De map met bestanden is je inhoud.

Het zijn bovendien open formaten waar geen leverancier eigenaar van is. Elke gangbare static site generator leest Markdown, YAML en JSON. Bij een overstap naar een andere generator moeten de sjablonen en de vormgeving opnieuw, maar je teksten en gegevens blijven gewoon staan. Hoe de bekende generatoren van elkaar verschillen, staat in static site generator kiezen. Die bestanden zijn bovendien van jou: de projectmap staat op jouw naam of je hebt er volledige toegang toe. Wissel je ooit van beheerder, ook weg van mij, dan neem je ze gewoon mee.

Dat is een groot verschil met een page builder, die je opmaak en tekst als instellingen in een database bewaart. Daar haal je de inhoud er niet zomaar netjes uit. Waarom code in tekstbestanden ook voor AI beter werkt, staat in page builder of code. En wil je later toch zelf teksten aanpassen in een beheerscherm, dan kan dat bovenop dezelfde bestanden, met een Git-based CMS.

Eén kanttekening. Niet alles hoort in deze bestanden. Inzendingen van formulieren en gegevens van klanten worden apart opgeslagen. Zeker gevoelige gegevens, zoals de inschrijvingen via een versleuteld formulier, horen in een aparte, beveiligde opslag en nooit in de projectmap. Grote foto's en video's staan vaak ook op een eigen plek.

Waar het misgaat in Markdown, YAML en JSON

De meeste problemen met deze bestanden komen terug op een handvol fouten. Ze laten een build mislukken of zetten iets stilletjes verkeerd op de site. Bij mijn eigen werk houdt de build de meeste tegen voordat er iets live gaat, en de rest zie ik bij mijn controle.

  • Tabs in YAML. YAML verbiedt tabs voor het inspringen; alleen spaties tellen.
  • Een dubbele punt in een tekst zonder aanhalingstekens. titel: "Let op: nieuw" werkt, titel: Let op: nieuw breekt.
  • Een komma achter het laatste onderdeel in JSON. Die mag er niet staan.
  • Enkele aanhalingstekens in JSON. JSON kent alleen dubbele aanhalingstekens.
  • Front matter zonder sluitende streepjes. Dan leest de generator het hele artikel als gegevens.
  • Datums in wisselende schrijfwijzen. Dan klopt de volgorde in overzichten niet meer; één vaste vorm, jaar-maand-dag, voorkomt dat.
  • Koppen overslaan in Markdown. Van twee naar vier hekjes springen breekt de logische kopvolgorde, en die hebben bezoekers met een schermlezer nodig.
  • Een andere tekencodering dan UTF-8. Dan veranderen letters als é en ë in rare tekens. De JSON-standaard schrijft UTF-8 voor bij uitwisseling tussen systemen.

Conclusie: drie simpele formaten, met strenge regels

Markdown is voor tekst, YAML voor gegevens die mensen bijhouden en JSON voor gegevens tussen systemen. Samen vormen ze de basis van veel snelle, statische websites, met de front matter als brug tussen tekst en gegevens. Het grote voordeel is dat het gewone tekstbestanden zijn. Mensen en AI kunnen ze lezen, elke wijziging is zichtbaar in versiebeheer en verhuizen is vooral kopiëren. De keerzijde zijn de strenge regels: één spatie of komma verschil kan een site breken.

Voor jou betekent dat: je inhoud staat in open bestanden die van jou zijn, en je hoeft ze zelf nooit te openen. Ik houd ze bij, en wat er verandert, loop ik na voordat het live staat. Wil je weten hoe ik bepaal welke gegevens in welke velden horen, lees dan contentmodel. Wil je zien hoe ik werk, download dan het pitchdeck.

Veelgestelde vragen

Wat is het verschil tussen YAML en JSON?

Beide zijn formaten voor gegevens, zoals een lijst met openingstijden of de instellingen van een site. YAML is gemaakt om door mensen gelezen en bewerkt te worden: weinig leestekens, inspringen in plaats van haakjes en ruimte voor opmerkingen. JSON is strenger, met accolades, aanhalingstekens en komma's, en is de standaard waarmee systemen gegevens uitwisselen. Opmerkingen kunnen er niet in. Sinds YAML 1.2 is elk geldig JSON-bestand ook geldige YAML. Voor bestanden die mensen bijhouden is YAML vaak de keuze, voor gegevens tussen systemen JSON.

Met welk programma open je een Markdown-bestand?

Met elk programma dat gewone tekst kan openen, zoals Kladblok op Windows of TextEdit op de Mac. Je ziet dan de tekst met de hekjes en sterretjes erin, en die is prima te lezen. Wie ook wil zien hoe de opmaak eruitziet, gebruikt een editor met een voorbeeldweergave, zoals Visual Studio Code. Op een website zet de static site generator de Markdown automatisch om in een opgemaakte webpagina. Heb je een vaste beheerder, dan hoef je die bestanden zelf niet te openen: je geeft door wat er moet veranderen.

Wat is front matter?

Front matter is een blokje gegevens bovenaan een Markdown-bestand, tussen twee regels met drie streepjes. Er staan gegevens in over de pagina zelf, zoals de titel, de datum, de beschrijving voor Google en de categorie. Meestal is het geschreven in YAML. Daaronder volgt de eigenlijke tekst in Markdown. Een static site generator zoals Eleventy leest de front matter en gebruikt die gegevens, bijvoorbeeld om de titel in de browser te tonen of artikelen op datum te sorteren.

Kun je opmerkingen zetten in een JSON-bestand?

Nee, niet volgens de standaard. De officiële beschrijving van JSON kent geen opmerkingen, dus een regel met uitleg ertussen maakt het bestand ongeldig voor de meeste programma's. Sommige programma's accepteren een variant met opmerkingen, maar daar kun je niet overal op rekenen. Moet er uitleg bij gegevens staan, dan is YAML de betere keuze, want daar is alles na een hekje een opmerking. Of de uitleg komt in een apart tekstbestand naast het JSON-bestand.

Benieuwd hoe ik dit in de praktijk aanpak?

Het pitchdeck laat de hele werkwijze zien.

Geschreven door

Marketing freelancer uit 's-Hertogenbosch. Volg op LinkedIn (opent in een nieuw tabblad)