Codeblokken in Markdown: Complete handleiding met syntax, talen en voorbeelden

Hier beoordeel ik Codeblock-opties in Markdown—hoe je de programmeertaal, diff-opmaak en de bestandsnaam van een codeblok kunt specificeren.

Deze gids is onderdeel van onze Documentatietools in 2026: Markdown, LaTeX, PDF & Printworkflows hub.

Overzicht van Markdown-codeblokken

Markdown-codeblokken tonen code of vooraf opgemaakte tekst binnen Markdown-documenten, waarbij de opmaak behouden blijft en optioneel syntaxismarkering mogelijk is. Er zijn twee hoofdtypen code-opmaak in Markdown: inline code en codeblokken.

Typen Markdown-codeblokken

Belangrijkste verschillen

• Inline code gebruikt enkele backticks (`) en is bestemd voor korte codefragmenten binnen een zin.
• Ingekliepte codeblokken gebruiken vier spaties of een tab aan het begin van elke regel. Ze ondersteunen geen syntaxismarkering en komen zelden voor in modern Markdown.
• Gecombineerde codeblokken gebruiken drievoudige backticks (```) of tildes (~~~) voor en na de code. Dit is de aanbevolen methode, vooral op platforms zoals GitHub, omdat:
  • Ze gemakkelijker te lezen en schrijven zijn.
  • Je de programmeertaal direct na de openingsbackticks kunt specificeren voor syntaxismarkering.
  • Ze de opmaak behouden en meerdere regels code ondersteunen.

Voorbeeld van een gecombineerd codeblok met syntaxismarkering:

Wanneer we de volgende Markdown-opgemaakte tekst hebben:

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

De weergegeven output ziet er als volgt uit:

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

Beste praktijken voor Markdown-codeblokken

• Gebruik gecombineerde codeblokken (drievoudige backticks) voor meerdere regels code om duidelijkheid en compatibiliteit tussen platforms te waarborgen.
• Specificeer de taal na de openingsbackticks voor syntaxismarkering (bijv. ```python).
• Gebruik inline code voor korte fragmenten of commando’s binnen tekst.
• Vermijd ingekliepte codeblokken, tenzij vereist voor compatibiliteit met oudere systemen, aangezien ze geen syntaxismarkering ondersteunen en minder leesbaar kunnen zijn.
• Plaats een lege regel voor en na gecombineerde codeblokken om de leesbaarheid in ruwe Markdown te verbeteren.

Speciale functies

• Sommige platforms ondersteunen aanvullende taalidentificatoren, zoals diff voor het tonen van codeveranderingen, wat toegevoeg of verwijderde regels in code reviews markeert.
• Om backticks binnen een codeblok weer te geven, moet je het blok omgeven met een hoger aantal backticks (bijv. vier backticks om drie backticks binnenin weer te geven).

Snelle referentie

Gebruik gecombineerde codeblokken met een taalidentificator voor de beste leesbaarheid en syntaxismarkering. Behoud inline code voor korte fragmenten en vermijd ingekliepte blokken, tenzij dit noodzakelijk is voor compatibiliteit.

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

Diff Syntaxismarkering

Diff syntaxismarkering stelt je in staat om codeveranderingen duidelijk te tonen — handig in documentatie, code reviews en technische blogs.

• Gebruik gecombineerde codeblokken met drievoudige backticks (```) om je blok te beginnen en te beëindigen.
• Specificeer diff als taalidentificator direct na de openingsbackticks.

Voorbeeld:

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

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

Beste praktijken:

• Plaats een lege regel voor en na je codeblok voor betere leesbaarheid in ruwe Markdown.
• Let op: diff-markering kleurt alleen hele regels op basis van het leidende karakter; het markeert geen inline veranderingen binnen een regel.

Tip: Diff-markering wordt breed ondersteund op GitHub, GitLab en de meeste Markdown-renderers, waardoor het een betrouwbare keuze is voor het communiceren van codeveranderingen.

Ondersteunde talen voor syntaxismarkering

De exacte set ondersteunde talen hangt af van de renderer of het platform dat je gebruikt. Markdown doorgeeft de taalidentificator aan de renderengine, die de juiste syntaxismarkering toepast. Dit is van belang bij het converteren van HTML naar Markdown met Python, aangezien <code> tags met taalclass-attributen (bijv. class="language-python") direct worden toegewezen aan deze identificatoren in het gecombineerde blok.

Veelvoorkomende 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 & Configuratie: markdown, ini, toml, dockerfile, makefile
• Speciaal: diff, mermaid, geojson, topojson, stl (voor diagrammen en datavisualisaties op GitHub) — de mermaid identificator stelt in het bijzonder volledige diagramrendering in op ondersteunde platforms; zie de Mermaid Diagrammen Quickstart en Cheat Sheet voor een complete syntaxisreferentie en Hugo-instellingsgids
• Andere: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme, en vele meer

Hoe een taal te specificeren:

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

Taalidentificatoren ondersteund door de meeste renderers:

Opmerking: De meeste renderers zijn niet-casegevoelig voor taalnomen. Als je een niet-ondersteunde identificator gebruikt, wordt het codeblok weergegeven als platte tekst.

De volledige lijst met ondersteunde talen vinden:

• GitHub: Gebruikt Linguist, met ondersteuning voor honderden talen.
• VS Code & vele webrenderers: Gebruiken highlight.js of Pygments—bekijk hun documentatie voor uitputtende lijsten.
• Bitbucket: Verwijst naar CodeMirror modes en Pygments lexers.

Een bestandsnaam specificeren in een Markdown-codeblok

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

1. Bestandsnaam in de codebloklabel (Meta Syntaxis)

Sommige Markdown-engines (bepaalde statische sitegenerators en documentatieplatforms) ondersteunen een meta syntaxis waarbij je de bestandsnaam na de taal toevoegt, gescheiden door een dubbele punt:

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

Dit toont de bestandsnaam boven of naast het codeblok. De Hugo-renderer van deze site ondersteunt dit niet:

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

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

2. Handmatige bestandsnaam als kop of inline code

Voor universele compatibiliteit (inclusief GitHub, Stack Overflow en de meeste Markdown-renderers), plaats de bestandsnaam boven het codeblok met vetgedrukte 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 wanneer je wilt dat de bestandsnaam zichtbaar blijft bij het kopiëren van de code.

Compatibiliteitsoverzicht

Gebruik vetgedrukte inline code boven het codeblok voor maximale compatibiliteit, en overweeg een commentaar binnen de code voor duidelijkheid bij het delen tussen platforms.

Backticks ontsnappen binnen codeblokken

Om backtick-omheiningen binnen een codeblok weer te geven — bijvoorbeeld bij het schrijven van documentatie over Markdown zelf — nest je het blok in een hoger aantal backticks:

````markdown
```python
# Deze drievoudige backtick-omheining bevindt zich binnen een vier-voudige backtick-omheining
print("hello")
```
````

Het gebruik van vier backticks als buitenste omheining stelt je in staat om drievoudige backtick-voorbeelden binnenin te tonen, wat handig is voor Markdown-tutorials en cheat sheets.

Hugo-specifiek: De Highlight Shortcode

Als je Hugo gebruikt, biedt de ingebouwde highlight shortcode meer controle dan gewone gecombineerde blokken, inclusief regelnummers en gemarkeerde 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 — markeer regels 2 en 4
• linenostart=10 — start regelnummering bij 10

Dit is bijzonder nuttig in tutorials of documentatie waarbij je de aandacht wilt vestigen op specifieke regels. Zie de Markdown Cheat Sheet voor meer opmaakfuncties, en de Hugo Cheat Sheet voor een breder referentie over Hugo-commando’s en sjablonen.

Nuttige links

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