Sessie 16: Markdown: Schrijf notities die eruitzien als het web

Je kent HTML misschien van het internet: <h1>, <p>, <a>. Maar voor notities en documentatie is HTML veel te veel typwerk. Daar is Markdown voor.

Markdown is een mini-taal die je in gewone tekst schrijft. Het ziet er leesbaar uit zónder dat je het eerst moet omzetten. En met één druk op de knop wordt het nette HTML: koppen, lijsten, links, tabellen.

In deze sessie leer je de hele basis van Markdown. Aan het einde schrijf je notities die er professioneel uitzien, op GitHub, in Obsidian, of in elk ander programma dat Markdown begrijpt.

Wat je vandaag leert

Koppen en alinea’s maken
Tekst opmaken: vet, cursief, doorstreept
Lijsten en opsommingen
Links naar andere pagina’s en websites
Afbeeldingen invoegen
Tabellen maken
Horizontale lijnen en codeblokken

Waarom Markdown?

Markdown is overal:

GitHub: elke repo heeft een README.md in Markdown. Issues, pull requests, wiki’s: allemaal Markdown.
Obsidian, Joplin, Logseq: notitie-apps die je documenten als .md-bestanden opslaan.
Discord, Slack, Reddit: ondersteunen Markdown voor snelle opmaak in berichten.
Hugo (deze website!): alle sessie-pagina’s die je hier ziet, zijn geschreven in Markdown.
Jupyter Notebooks: de tekst-cellen zijn Markdown.

Het grote voordeel: je schrijft gewone tekst. Geen ingewikkelde tags. En het resultaat is altijd leesbaar, ook als platte tekst.

Stap 0: Een Markdown-bestand maken

Markdown-bestanden eindigen op .md. Maak er één:

mkdir mijn-notities
cd mijn-notities
echo "# Mijn Eerste Notitie" > test.md

Je kunt .md-bestanden openen in elke teksteditor: Kladblok, VS Code, Thonny, Obsidian. VS Code heeft een ingebouwde preview: klik rechtsboven op het icoontje met het vergrootglas en het boek.

Stap 1: Koppen en alinea’s

Koppen maak je met #. Hoe meer #, hoe kleiner de kop:

# Dit is een titel (h1)

## Dit is een subtitel (h2)

### Dit is een kleinere kop (h3)

#### Nog kleiner (h4)

Een alinea maak je door gewoon tekst te typen. Een lege regel ertussen start een nieuwe alinea:

Dit is de eerste alinea. Die loopt gewoon door.

Dit is de tweede alinea. Omdat er een lege regel tussen zit.

Tip: één # gebruik je maar één keer per document: voor de titel. De rest begint bij ##.

Stap 2: Tekst opmaken

**Dit is vetgedrukt**

*Dit is cursief*

~~Dit is doorstreept~~

Je kunt ook **vet en *cursief* combineren** in dezelfde zin.

Het resultaat:

**vet** wordt vet
*cursief* wordt cursief
~~doorstreept~~ wordt ~~doorstreept~~

Let op: geen spaties tussen de sterretjes en de tekst. ** vet ** werkt niet. **vet** wel.

Sommige editors accepteren ook underscores: __vet__ en _cursief_. Maar sterretjes zijn de standaard: gebruik die.

Stap 3: Horizontale lijnen

Een horizontale lijn maak je met drie (of meer) streepjes:

---

Of met sterretjes:

***

Het resultaat is een lijn over de hele breedte. Gebruik het spaarzaam: één of twee per document is genoeg. Te veel lijnen maken je notities onoverzichtelijk.

Stap 4: Lijsten

Ongenummerde lijst

Gebruik -, * of +:

- Python
- Git
- Markdown
- GitHub

Je kunt lijsten nesten door in te springen (2 of 4 spaties):

- Programmeertalen
  - Python
  - JavaScript
- Versiebeheer
  - Git
  - GitHub

Genummerde lijst

1. Open Thonny
2. Schrijf je code
3. Klik op Run

Het maakt niet uit welke nummers je typt: Markdown nummert automatisch door. Dit:

1. Stap één
1. Stap twee
1. Stap drie

…geeft exact hetzelfde resultaat als 1, 2, 3. Handig als je later een stap wilt toevoegen zonder alles te hernummeren.

Checklist (GitHub-stijl)

- [x] Git installeren
- [x] Eerste commit maken
- [ ] Branches leren
- [ ] Pull request openen

[x] is afgevinkt, [ ] is open. Werkt in GitHub issues, pull requests, en veel notitie-apps.

Stap 5: Links

Externe links (naar websites)

[klik hier voor de CoderDojo-site](https://python.coderdojohasselt.be)

Het woord tussen [ ] is de klikbare tekst. De URL tussen ( ) is de bestemming.

Interne links (naar andere pagina’s in je project)

[Bekijk sessie 11](11-git-intro/)

Dit linkt naar het bestand 11-git-intro/_index.md in dezelfde map.

Snel-link (toon de URL direct)

<https://github.com>

Dit toont de URL als klikbare link, zonder aparte tekst.

Stap 6: Afbeeldingen

Een afbeelding is bijna hetzelfde als een link, maar met een ! ervoor:

![Een ster in Pygame Zero](/sessions/01-catch-the-stars/coordinaten.svg)

De tekst tussen [ ] is de alt-tekst: die verschijnt als de afbeelding niet laadt, of wordt voorgelezen door screenreaders.

Afbeeldingen en Git: Kleine afbeeldingen (SVG, kleine PNG’s) kun je in Git zetten. Grote afbeeldingen (>1 MB) en video’s beter niet, want die maken je repo traag.

Stap 7: Tabellen

| Commando | Wat het doet |
|----------|-------------|
| `git init` | Nieuwe repository maken |
| `git add` | Bestanden klaarzetten voor commit |
| `git commit` | Wijzigingen vastleggen |
| `git push` | Commits naar GitHub sturen |

De | tekens vormen de kolommen. De --- regel scheidt de kop van de data. De : in de scheidingsregel bepaalt uitlijning:

| Links uitgelijnd | Gecentreerd | Rechts uitgelijnd |
|:-----------------|:-----------:|------------------:|
| links            | midden      | rechts            |

Stap 8: Code en codeblokken

Inline code

Gebruik backticks voor korte stukjes code in een zin:

Gebruik `git status` om te zien wat er gewijzigd is.

Codeblokken

Voor meerdere regels code gebruik je drie backticks:

```python
def groet(naam):
    return f"Hallo {naam}!"
```

De taal (python) achter de eerste backticks geeft syntax highlighting. Dit werkt voor tientallen talen: bash, html, css, javascript, json, yaml, markdown.

Codeblok zonder taal

```
Dit is gewoon tekst
zonder syntax highlighting
```

Stap 9: Blockquotes

Gebruik > voor citaten of belangrijke opmerkingen:

> Git is geen back-up. Git is een tijdmachine.
> Iemand op het internet

Meerdere > regels achter elkaar vormen één blok. Een lege > regel start een nieuwe alinea binnen het citaat.

Stap 10: Alles samen: een echte README

Een goed README.md combineert alles wat je nu kent. Hier is een voorbeeld:

# Mijn Project

Een korte beschrijving van wat dit project doet.

## Installatie

```bash
git clone https://github.com/jouw-naam/mijn-project.git
cd mijn-project
```

## Gebruik

1. Open `main.py` in Thonny.
2. Klik op **Run**.
3. Kies een level en start.

## Wat je leert

- [x] Pygame Zero basis
- [x] Collision detection
- [ ] Highscore systeem
- [ ] Geluidseffecten

## Links

- [CoderDojo Hasselt](https://coderdojohasselt.be)
- [Broncode op GitHub](https://github.com/jouw-naam/mijn-project)

Cheatsheet

Wat	Markdown
Kop niveau 1	`# Titel`
Kop niveau 2	`## Subtitel`
Kop niveau 3	`### Kleinere kop`
Vet	`vet`
Cursief	`cursief`
Doorstreept	`~~doorstreept~~`
Horizontale lijn	`---` of `***`
Lijst (ongeordend)	`- item`
Lijst (genummerd)	`1. item`
Checklist	`- [ ] open item`
Link	`[tekst](url)`
Afbeelding	`![alt tekst](url)`
Inline code	`code`
Codeblok	```taal
Citaat	`> citaat`
Tabel	`\| kolom \| kolom \|`

Showcase

Laat aan een coach en een buddy zien:

Een Markdown-document met minstens één kop, een lijst, een link en vetgedrukte tekst.
Een tabel met minstens twee kolommen en drie rijen.
Een checklist met afgevinkte en open items.

Tot de volgende keer!

Markdown is simpel, maar het is overal. Je README’s op GitHub, je notities in Obsidian, je documentatie: alles wordt leesbaarder met Markdown. Gebruik het. Overdrijf niet met opmaak. Goeie notities zijn helder, niet druk.

Neem mee naar huis

Makkelijk: Schrijf een README.md voor je favoriete Python-project. Gebruik koppen, een lijst en een codeblok.
Middel: Maak een notitie in Obsidian (of een andere Markdown-editor) over wat je deze maand geleerd hebt. Gebruik alle opmaak uit de cheatsheet minstens één keer.
Lastig: Bouw een “cheatsheet”-pagina in Markdown voor een onderwerp naar keuze (Git-commando’s, Python syntax, wiskunde-formules). Gebruik tabellen en geneste lijsten.
Erg lastig: Maak een Markdown-document met een geneste lijst die minstens drie niveaus diep gaat, een tabel met uitlijning, en een codeblok met syntax highlighting.