# Markdown De opmaaktaal van elke README, elk Discord-bericht en elk antwoord van een chatbot. Een uur leren, jaren gebruiken. Multimedia & Creatieve Technologie · 0.0 General · Zelfstudie · versie 1.0.1 · 2026-09-30 Tags: markdown, github Slides: Speaker notes: ## Agenda 1. Waarom markdown: Opmaak die je typt 2. De basis: Titels, tekst, lijsten, links 3. Speeltuin: Zelf typen en meekijken 4. GitHub flavored: Tabellen, taken, alerts 5. In de praktijk: README, Discord, Obsidian, PDF 6. Oefenen: Drills, quiz, zelf schrijven ## Zelfstudie: Werkwijze *45 minuten, Alleen* Neem er drie kwartier voor. De syntaxslides zijn naslag, de speeltuin en de drills zijn het echte werk. 1. Typ elk voorbeeld zelf over in de speeltuin, wijzig er iets aan en kijk wat er kantelt 2. De acht drills staan achteraan. Ze zijn af als alle bolletjes groen staan 3. Twee quizzen tussendoor: antwoord eerst, lees daarna de uitleg 4. Sluit af met een eigen tekst in markdown ## 1. Waarom markdown *Opmaak die je typt in plaats van aanklikt, en die over tien jaar nog leesbaar is.* **Opmaak zonder knopjes.** Je zet een paar tekens tussen je tekst. Een renderer maakt er HTML van. Het bestand zelf blijft gewone tekst die elke editor opent. ### Waar je het tegenkomt - De `README.md` van elk project op GitHub - Discord, Slack en Teams: je berichten zijn markdown - Notion, Obsidian, Bear en zowat elke notitie-app - Antwoorden van ChatGPT en Claude rollen er in binnen - Documentatiesites, blogs, changelogs - Issues, pull requests en code reviews > [!NOTE] > **Eén syntax, overal** > > De verschillen tussen die tools zitten in de extra's. De basis is overal dezelfde. ### Van tekens naar HTML *Een renderer leest je tekens en zet er HTML tags voor in de plaats.* ### Waarom geen Word #### Word en Google Docs - De opmaak zit verstopt in een binair bestand - Een diff is onleesbaar, versies vergelijken lukt niet - Kopiëren naar het web geeft rommel-HTML - Je muis doet het werk #### Markdown - Platte tekst, elke editor opent het - Git ziet regel per regel wat veranderde - Hetzelfde bestand wordt HTML, PDF of slides - Je handen blijven op het toetsenbord ### Waar het vandaan komt *John Gruber schreef het om mails leesbaar te houden. Twintig jaar later staat het in elke tool.* - **2004** Markdown 1.0: John Gruber en Aaron Swartz - **2012** Wildgroei: Elke tool zijn eigen variant - **2014** CommonMark: Een strikte spec, eindelijk - **2017** GitHub Flavored: Tabellen, taken, autolinks - **nu** Overal: Van chatbots tot statische sites ### Wat staat er in een .md bestand? - A. Gewone tekst - B. HTML - C. Een binair formaat zoals .docx - D. JSON **Antwoord:** A. Gewone tekst Platte tekst met een handvol afgesproken tekens. De tool die het toont, maakt er HTML van. Daarom opent een .md bestand overal, ook in Kladblok. ## 2. De basis *Tien tekens waar je negentig procent van de tijd mee toekomt.* ### Titels *Eén tot zes hekjes, gevolgd door een spatie.* > [!WARNING] > Zonder spatie na het hekje gebeurt er niets. `#Titel` blijft gewoon tekst. Eén `#` per bestand is genoeg, dat is je paginatitel. ### Alinea's en regeleindes *Een witregel begint een nieuwe alinea. Eén enter telt niet mee.* > [!TIP] > Twee spaties op het einde van een regel doen hetzelfde, maar die zie je niet staan. De backslash wel. ### Vet, cursief, geschrapt *Sterretjes en underscores doen hetzelfde. Kies er één en hou die aan.* > [!TIP] > Sterretjes werken altijd. Underscores breken soms midden in een woord, denk aan `snake_case_namen`. ### Code in een zin *Backticks rond een commando, een bestandsnaam of een stukje code.* ### Lijsten *Een streepje voor een bolletje, een cijfer met een punt voor een nummering.* > [!TIP] > De cijfers hoeven niet te kloppen. Schrijf drie keer `1.` en de renderer telt zelf door. Scheelt werk als je later een stap tussenvoegt. ### Nesten en takenlijstjes *Twee spaties inspringen maakt een subniveau. Vakjes met haakjes worden aanvinkbaar.* > [!WARNING] > Takenlijstjes zijn GitHub-gebied. In een issue kan je ze aanvinken met de muis, en GitHub telt hoeveel er af zijn. ### Links *Tekst tussen rechte haakjes, het adres tussen ronde.* > [!TIP] > Goede linktekst zegt waar hij naartoe gaat. Het woord "hier" zegt niets, en een screenreader leest alleen de link voor. ### Afbeeldingen *Dezelfde syntax als een link, met een uitroepteken ervoor.* > [!NOTE] > De tekst tussen de haakjes is de alt-tekst: voor screenreaders, en voor iedereen bij wie het pad fout staat. ### Citaten *Een groter-dan-teken voor de regel. Werkt ook voor meerdere alinea's.* ### Codeblokken *Drie backticks, de taalnaam erachter, drie backticks om af te sluiten.* > [!TIP] > De taalnaam zorgt voor de kleuren. Laat je ze weg, dan krijg je grijze tekst. `js`, `php`, `bash`, `json`: GitHub kent er honderden. ### Tabellen *Pipes tussen de kolommen, een rij streepjes onder de koppen.* > [!TIP] > De pipes hoeven niet onder elkaar te staan, dat is enkel voor jezelf. Met `:---` of `---:` lijn je een kolom links of rechts uit. ### Lijn en escapen *Drie streepjes trekken een scheiding. Een backslash escapet een teken, zodat het gewone tekst blijft.* ### Welke regel maakt een titel van het tweede niveau? - A. ## Sectie - B. \*\*Sectie\*\* - C. 2. Sectie - D. == Sectie == **Antwoord:** A. ## Sectie Het aantal hekjes is het niveau, van 1 tot 6. De spatie erna is verplicht. ### Speeltuin ## 3. GitHub flavored *De extra's die GitHub bovenop de standaard legt. De helft daarvan is ondertussen overal overgenomen.* ### Wat GFM erbij doet *CommonMark is de strikte basis. GitHub Flavored Markdown legt daar een laag bovenop.* - **Tabellen**: Pipes en streepjes, met uitlijning per kolom. - **Takenlijstjes**: Vakjes die je in een issue aanvinkt met de muis. - **Doorstreept**: Twee tildes rond de tekst. - **Autolinks**: Een kaal adres wordt vanzelf klikbaar. - **Voetnoten**: Verwijzingen onderaan de pagina. - **Alerts**: Gekleurde kaders voor een waarschuwing of een tip. ### Alerts *Een citaat met een label ervoor. GitHub tekent er een gekleurd kader van.* > [!NOTE] > Vijf soorten: NOTE, TIP, IMPORTANT, WARNING en CAUTION. Werkt in README's, issues en discussions. ### Emoji, mentions en verwijzingen *Deze drie werken alleen op GitHub zelf, niet in een willekeurige renderer.* | Wat je typt | Wat GitHub ervan maakt | | --- | --- | | `:tada:` | 🎉, en er zijn er duizend | | `@sam` | Een link naar het profiel, met een notificatie | | `#42` | Een link naar issue of pull request 42 | | `a1b2c3d` | Een link naar die commit | | `Closes #42` | Sluit issue 42 wanneer de pull request wordt gemerged | ### Diagrammen in een codeblok *Een codeblok met mermaid als taal wordt op GitHub een getekend diagram.* ````md ```mermaid flowchart LR A[Werkmap] --> B[Staging] B --> C[Repository] C --> D[GitHub] ``` ```` > [!NOTE] > Werkt in README's, issues en discussions, en in Notion en Obsidian via een plugin. In een gewone renderer blijft het een codeblok. ### Front matter *Een blok YAML tussen drie streepjes, helemaal bovenaan het bestand.* ```md --- title: Markdown leren date: 2026-09-20 tags: [docs, basis] draft: false --- # Markdown leren De tekst begint hier. ``` > [!NOTE] > Astro, Hugo, Jekyll, Docusaurus en Obsidian lezen dat blok uit: titel, datum en tags komen zo in je site of in je notities terecht. ### Smaken *Dezelfde basis, andere extra's. Weten welke smaak je voor je hebt scheelt frustratie.* | Smaak | Waar | Wat je erbij krijgt | | --- | --- | --- | | CommonMark | De strikte spec | Niets extra, alles precies gedefinieerd | | GitHub Flavored | GitHub, GitLab, Gitea | Tabellen, taken, alerts, autolinks | | MDX | Astro, Docusaurus, Next | React componenten tussen je tekst | | Obsidian | Notities | Wikilinks, tags, eigen callouts | | Discord | Chat | Spoilers, geen tabellen of afbeeldingen | ### HTML tussen je markdown *Lukt iets niet met markdown, dan mag je HTML schrijven. GitHub laat een beperkte set door.* ```md
Installatie voor Windows Hier staat de uitleg die pas verschijnt na een klik.
Logo ``` > [!WARNING] > Scripts en styles filtert GitHub weg. En markdown binnen een HTML tag werkt alleen met een witregel ertussen, zoals hierboven. ## 4. In de praktijk *Waar je markdown deze week al nodig hebt.* ### Wat in een README hoort - De naam en één zin: wat is dit en voor wie - Een screenshot of een gif, zodat niemand moet raden - Installatie: de commando's die werken op een lege machine - Gebruik: het kleinste voorbeeld dat iets doet - De scripts en de configuratie die erbij horen - Licentie, credits en hoe iemand kan bijdragen > **Voor wie schrijf je dat?** > > Voor jezelf over drie maanden, voor de lector die je project opent, en voor de werkgever die je GitHub doorneemt. ### Een README die het werk doet *Veertig regels markdown, en iedereen weet wat je gebouwd hebt.* ### Discord en Slack *Chat gebruikt dezelfde tekens, met een kortere lijst.* #### Werkt - `**vet**`, `*cursief*`, `~~geschrapt~~` - Inline `` `code` `` en codeblokken met een taal - Citaten met `>`, ook over meerdere regels - Spoilers met `||verborgen||` - Lijsten, sinds kort ook genummerd #### Werkt niet - Tabellen - Afbeeldingen via markdown, je sleept ze gewoon in het venster - Titels met hekjes in Slack, Discord kent ze wel - HTML ### Notities in Obsidian *Markdown-bestanden in een map op je schijf. Geen database, geen abonnement, geen lock-in.* ```md --- tags: [school, git] --- # Git basics Zie [[Terminal commando's]] voor de shell. > [!tip] Sneltoets > Cmd+E wisselt tussen bron en weergave. - [ ] Oefening afwerken voor vrijdag ``` > [!TIP] > De dubbele haakjes zijn Obsidian, geen standaard markdown. Elders blijven ze staan als tekst. Alles wat je in Obsidian typt, opent ook in VS Code. ### Van markdown naar iets anders *Hetzelfde .md bestand, andere uitvoer. Er bestaat een tool voor elk van deze drie.* - **Een PDF**: Je schrijft je verslag in markdown, een tool maakt er een PDF van. Geen gevecht met opmaak in Word. - **Een website**: Blogs en documentatiesites draaien vaak op een map met .md bestanden. - **Slides**: Ook een presentatie kan gewoon een markdown-bestand zijn. ### Waarom een chatbot markdown uitspuwt - Het model is getraind op GitHub, Stack Overflow en documentatie, allemaal markdown - Opmaak in platte tekst past in dezelfde stroom tokens als de rest van het antwoord - De chat-interface rendert het, dus jij ziet titels en lijsten - Kopieer je het antwoord naar je README, dan staat de opmaak er meteen goed in ## 5. Oefenen *Acht drills, twee quizzen en een tekst van jezelf.* ### Drills *Links typen tot de rechterkant hetzelfde toont als het doel erboven.* ### Waarom staan `Eerste regel` en `Tweede regel` na elkaar op dezelfde lijn? - A. Er staat geen witregel tussen - B. Markdown kent geen regeleindes - C. De regels zijn te kort - D. Er ontbreekt een streepje **Antwoord:** A. Er staat geen witregel tussen Eén enter is voor een renderer gewoon een spatie. Een witregel maakt een nieuwe alinea, een backslash of twee spaties maken een regeleinde binnen dezelfde alinea. ### Wat toont een lijst die drie keer met `1.` begint? - A. 1, 2, 3 - B. Drie keer 1 - C. Een foutmelding - D. Bolletjes **Antwoord:** A. 1, 2, 3 De renderer telt zelf door, het eerste cijfer bepaalt waar hij begint. Daarom kan je een stap tussenvoegen zonder de rest te hernummeren. ### Spiekbriefje *Alles wat je dagelijks nodig hebt, op één scherm.* ### Opdracht: Schrijf iets in markdown *15 minuten, Alleen* Neem iets wat je toch al moet opschrijven: notities van een les, een recept, de uitleg van een project. 1. Een titel en twee secties met een subtitel 2. Een lijst en een tabel 3. Een link, en een commando of stukje code 4. Een citaat of een alert 5. Typ het in VS Code en bewaar het als notities.md ### Verder lezen *Drie bronnen die de moeite waard zijn, en een spec voor wie het precies wil weten.* - **[markdownguide.org](https://www.markdownguide.org/)**: Het beste overzicht, met een cheat sheet en de verschillen per tool. - **[commonmark.org](https://commonmark.org/)**: De spec, met een live editor waarin je de parser ziet werken. - **[docs.github.com](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)**: Basic writing and formatting syntax: alles wat GitHub erbovenop doet. - **[marp.app](https://marp.app/)**: Slides uit markdown, zonder PowerPoint. ## Begrippen - **Markdown**: Een opmaaktaal in platte tekst. Je zet een paar afgesproken tekens rond je tekst en een renderer maakt er HTML van. John Gruber en Aaron Swartz bedachten het in 2004. (slide 9) - **Renderer**: Het programma dat je markdown leest en de tekens vervangt door HTML tags. Het .md bestand zelf blijft gewone tekst die elke editor opent. (slide 7) - **CommonMark**: De strikte spec van markdown, sinds 2014. Niets extra, wel alles precies gedefinieerd. De andere smaken leggen hun extra's daarbovenop. (slide 32) - **GitHub Flavored Markdown**: GFM. De laag die GitHub bovenop CommonMark legt: tabellen, takenlijstjes, doorstreepte tekst, autolinks, voetnoten en alerts. GitLab en Gitea gebruiken hem ook. (slide 27) - **Smaak**: Een variant van markdown: dezelfde basis, andere extra's. Weet welke smaak je voor je hebt, want een tabel werkt op GitHub en niet in Discord. (slide 32) - **MDX**: Markdown met React componenten tussen je tekst. Astro, Docusaurus en Next gebruiken het. (slide 32) - **Titel**: Eén tot zes hekjes met een spatie erna, het aantal hekjes is het niveau. Zonder spatie blijft #Titel gewone tekst. Eén # per bestand, dat is je paginatitel. (slide 12) - **Regeleinde**: Eén enter telt voor een renderer als een spatie, een witregel begint een nieuwe alinea. Een regeleinde binnen dezelfde alinea maak je met een backslash op het einde van de regel. (slide 13) - **Inline code**: Backticks rond een commando, een bestandsnaam of een stukje code in een zin: \`npm run dev\`. (slide 15) - **Codeblok**: Drie backticks met de taalnaam erachter, dan de code, en drie backticks om af te sluiten. De taalnaam (js, php, bash) zorgt voor de kleuren, zonder krijg je grijze tekst. (slide 21) - **Takenlijstje**: Een lijst met \[ \] of \[x\] direct na het streepje. Op GitHub vink je ze in een issue aan met de muis, en GitHub telt hoeveel er af zijn. (slide 17) - **Alt-tekst**: De tekst tussen de rechte haakjes van een afbeelding: !\[alt-tekst\](pad). Voor screenreaders, en voor iedereen bij wie het pad fout staat. (slide 19) - **Tabel**: Pipes tussen de kolommen en een rij streepjes onder de koppen. Met :--- of ---: lijn je een kolom links of rechts uit. Discord kent ze niet. (slide 22) - **Escapen**: Een backslash voor een teken, zodat het gewone tekst blijft. Met \\\* blijft een sterretje staan, met \\# wordt het geen titel. (slide 23) - **Alert**: Een citaat met een label ervoor, zoals > \[!NOTE\], dat GitHub als gekleurd kader tekent. Er zijn er vijf: NOTE, TIP, IMPORTANT, WARNING en CAUTION. (slide 28) - **Front matter**: Een blok YAML tussen drie streepjes, helemaal bovenaan een .md bestand. Astro, Hugo, Jekyll en Obsidian halen er titel, datum en tags uit. (slide 31) - **Mermaid**: Een codeblok met mermaid als taal, dat GitHub als diagram tekent. In een gewone renderer blijft het een codeblok. (slide 30) - **Wikilink**: Een link naar een andere notitie tussen dubbele rechte haakjes: \[\[Terminal commando's\]\]. Dat is Obsidian, geen standaard markdown, elders blijft het gewone tekst. (slide 38) - **README**: Het README.md bestand van een project: wat het is en voor wie, een screenshot, de installatie, het gebruik en de scripts. Zo moet niemand die je project opent raden. (slide 35) ## Links en bronnen ### In de presentatie - [markdownguide.org](https://www.markdownguide.org/) (slide 47) - [commonmark.org](https://commonmark.org/) (slide 47) - [docs.github.com](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) (slide 47) - [marp.app](https://marp.app/) (slide 47)