Markdown Codeblokken: Volledige Gids met Syntax, Talen & Voorbeelden

Hier bespreek ik Codeblock opties in Markdown — hoe je de programmeertaal, diff-formattering en bestandsnaam van een codeblock kunt specificeren.

Deze gids is onderdeel van onze Documentatie Tools in 2026: Markdown, LaTeX, PDF & Printing Workflows hub.

Overzicht van Markdown-codeblokken

Markdown-codeblokken tonen code of vooraf opgemaakte tekst binnen Markdown-documenten, terwijl de opmaak behouden blijft en optioneel syntaxiskleuring kan worden ingeschakeld. Er zijn twee hoofdtypes van codeopmaak in Markdown: inline-code en codeblokken.

Types van Markdown-codeblokken

Belangrijkste verschillen

• Inline-code gebruikt enkele backticks (`) en is bedoeld voor korte code binnen een zin.
• Ingeïndenteerde codeblokken gebruiken vier spaties of een tab aan het begin van elke regel. Ze ondersteunen geen syntaxiskleuring en zijn zeldzaam in moderne Markdown.
• Ongeschreven codeblokken gebruiken drievoudige backticks (```) of tildes (~~~) voor en na de code. Dit is de voorkeursmethode, vooral op platforms zoals GitHub, omdat:
  • Ze makkelijker leesbaar en te schrijven zijn.
  • Je kunt direct na de opening backticks de programmeertaal opgeven voor syntaxiskleuring.
  • Ze behouden de opmaak en ondersteunen meervoudige regels code.

Voorbeeld van een ongeschreven codeblok met syntaxiskleuring:

Wanneer we de volgende Markdown-geformateerde tekst hebben:

```python
def hello():
    print("Hello, world!")
```

Het gerenderde resultaat ziet er als:

def hello():
    print("Hello, world!")

Best practices voor Markdown-codeblokken

• Gebruik ongeschreven codeblokken (drievoudige backticks) voor meervoudige regels code om duidelijkheid en compatibiliteit over platforms te waarborgen.
• Specificeer de taal direct na de opening backticks voor syntaxiskleuring (bijvoorbeeld ```python).
• Gebruik inline-code voor korte fragmenten of opdrachten binnen tekst.
• Vermijd ingeïndenteerde codeblokken tenzij ze vereist zijn voor compatibiliteit met oudere systemen, omdat ze geen syntaxiskleuring ondersteunen en minder leesbaar zijn.
• Plaats een lege regel voor en na ongeschreven codeblokken om de leesbaarheid in ruwe Markdown te verbeteren.

Speciale functies

• Sommige platforms ondersteunen extra taalidentificatoren zoals diff om codeveranderingen weer te geven, wat toegevoegde of verwijderde regels in codebeoordelingen benadrukt.
• Om backticks binnen een codeblok weer te geven, omhul het blok met meer backticks (bijvoorbeeld vier backticks om drie backticks binnen te tonen).

Snelle verwijzingssamenvatting

Gebruik ongeschreven codeblokken met een taalidentificator voor de beste leesbaarheid en syntaxiskleuring. Reserveer inline-code voor korte fragmenten en vermijd ingeïndenteerde blokken tenzij het vereist is voor compatibiliteit.

Codeblokken passen natuurlijk samen met tabellen in Markdown om goed gestructureerde technische documentatie te bouwen.

Syntaxiskleuring met Diff

Diff-syntaxiskleuring laat je codeveranderingen duidelijk zien — handig in documentatie, codebeoordelingen en technische blogs.

• Gebruik ongeschreven codeblokken met drievoudige backticks (```) om je blok te beginnen en te eindigen.
• Specificeer diff als taalidentificator direct na de opening backticks.

Voorbeeld:

- oude regel die verwijderd wordt
+ nieuwe regel die toegevoegd wordt
  onveranderde regel

• Regels die beginnen met - worden benadrukt als verwijderingen (meestal rood).
• Regels die beginnen met + worden benadrukt als toevoegingen (meestal groen).
• Regels zonder voorvoegsel worden niet speciaal benadrukt.

Best practices:

• Plaats een lege regel voor en na je codeblok voor betere leesbaarheid in ruwe Markdown.
• Merk op dat diff-kleuring alleen hele regels kleurt op basis van het leidende karakter; het ondersteunt geen inlineveranderingen binnen een regel.

Tip: Diff-kleuring wordt breed ondersteund op GitHub, GitLab en meeste Markdown-renderers, waardoor het een betrouwbaar keuze is om codeveranderingen te communiceren.

Ondersteunde talen voor syntaxiskleuring

Het exacte aantal ondersteunde talen hangt af van de renderer of platform dat je gebruikt. Markdown geeft de taalidentificator door aan de rendering-engine, die de juiste syntaxiskleuring toepast. Dit is belangrijk bij het converteren van HTML naar Markdown met Python, aangezien <code>-tags met taalattributen (bijvoorbeeld class="language-python") direct overeenkomen met deze identificatoren in het ongeschreven blok.

Vaak ondersteunde talen op grote platforms (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe):

• Web & Scripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programmeren: python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• Data & Query: sql, r, matlab
• Markup & Config: markdown, ini, toml, dockerfile, makefile
• Speciaal: diff, mermaid, geojson, topojson, stl (voor diagrammen en datavisualisaties op GitHub)
• Andere: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme, en veel meer

Hoe een taal op te geven:

```python
def hello():
    print("Hello, world!")
```

Taalidentificatoren die het meeste renderers ondersteunen:

Opmerking: De meeste renderers zijn niet gevoelig voor hoofdletters in taalidentificatoren. Als je een onondersteunde identificator gebruikt, wordt het codeblok weergegeven als platte tekst.

Hoe de volledige lijst van ondersteunde talen te vinden:

• GitHub: Gebruikt Linguist, met ondersteuning voor honderden talen.
• VS Code & veel webrenderers: Gebruiken highlight.js of Pygments — zie hun documentatie voor uitgebreide lijsten.
• Bitbucket: Verwijst naar CodeMirror modi en Pygments lexers.

Een bestandsnaam specificeren in een Markdown-codeblok

Het tonen van de bestandsnaam naast een codeblok helpt lezers om te identificeren welk bestand een fragment behoort. Ondersteuning varieert per platform.

1. Bestandsnaam in het codebloklabel (meta syntax)

Sommige Markdown-engines (bepaalde statische sitegeneratoren en documentatieplatforms) ondersteunen een meta syntax waarbij je de bestandsnaam toevoegt na de taal, gescheiden door een dubbelepunt:

```js:app.js
console.log("Hello, world!");
```

Dit toont de bestandsnaam boven of naast het codeblok. Deze site’s Hugo renderer ondersteunt dit niet:

console.log("Hello, world!");

Opmerking: Dit wordt niet ondersteund in GitHub-flavored Markdown.

2. Handmatige bestandsnaamkop of inline-code

Voor universele compatibiliteit (inclusief GitHub, Stack Overflow en meeste Markdown-renderers), plaats de bestandsnaam boven het codeblok met vet inline-code:

**`app.js`**

```js
console.log("Hello, world!");
```

Of met een kop:

#### `app.js`

```js
console.log("Hello, world!");
```

Dit werkt overal en associeert visueel de bestandsnaam met het codeblok.

3. Bestandsnaam als commentaar binnen de code

Voeg de bestandsnaam toe als commentaar binnen het codeblok zelf:

```js
// app.js
console.log("Hello, world!");
```

Dit is vooral handig als je de bestandsnaam wilt laten zien wanneer de code wordt gekopieerd.

Compatibiliteitsoverzicht

Gebruik vet inline-code boven het codeblok voor maximale compatibiliteit, en overweeg commentaar binnen de code voor duidelijkheid bij het delen over platforms.

Backticks ontsnappen binnen codeblokken

Om backtick-fences binnen een codeblok weer te geven — bijvoorbeeld wanneer je documentatie over Markdown zelf schrijft — nest het blok in een groter aantal backticks:

````markdown
```python
# Deze drievoudige-backtick-fence is binnen een vier-backtick-fence
print("hello")
```
````

Het gebruik van vier backticks als buitenfence laat je drievoudige-backtickvoorbeelden tonen binnen, wat handig is voor Markdown-tutorials en cheetsheets.

Hugo-specifiek: De Highlight-kortcode

Als je Hugo gebruikt, biedt de ingebouwde highlight kortcode meer controle dan gewone ongeschreven blokken, waaronder regelnummers en uitgelichte regels:

{{< highlight python "linenos=true,hl_lines=2 4" >}}
def greet(name):
    print(f"Hello, {name}!")

greet("world")
{{< /highlight >}}

Opties:

• linenos=true — toon regelnummers
• hl_lines=2 4 — benadruk regels 2 en 4
• linenostart=10 — start regelnummering bij 10

Dit is vooral handig in tutorials of documentatie waarbij je aandacht wilt trekken naar specifieke regels. Zie de Markdown Cheatsheet voor meer opmaakfunctionaliteiten, en de Hugo Cheatsheet voor een breder overzicht van Hugo-opdrachten en sjablonen.

Nuttige links

• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks