Markdown-codeblokken - cheatsheet en voorbeelden van gebruik

Hier bespreek ik Codeblock opties in Markdown.

Markdown codeblokken

Markdown codeblokken zijn een manier om code of vooraf gedefinieerde tekst weer te geven binnen Markdown-documenten, terwijl de opmaak behouden blijft en optioneel syntaxisverlichting kan worden ingeschakeld. Er zijn twee hoofdtypes van codeformattering 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.
• Ingewikkelde codeblokken gebruiken vier spaties of een tab aan het begin van elke regel. Ze ondersteunen geen syntaxisverlichting en zijn minder gebruikelijk in moderne Markdown.
• Ongewone codeblokken gebruiken drievoudige backticks (```) of tildes (~~~) voor en na de code. Dit is de voorkeursmethode, vooral op platforms zoals GitHub, omdat:
  • Ze makkelijker te lezen en schrijven zijn.
  • Je kunt direct na de opening backticks de programmeertaal opgeven voor syntaxisverlichting.
  • Ze behouden de opmaak en ondersteunen meervoudige regel code.

Voorbeeld van een ongewone codeblok met syntaxisverlichting:

Wanneer we de volgende markdown opgemaakte tekst hebben:

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

Dan zou de weergegeven tekst er zo uitzien:

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

Best practices voor het gebruik van Markdown codeblokken

• Gebruik ongewone codeblokken (drievoudige backticks) voor meervoudige regel code om duidelijkheid en compatibiliteit over platforms te waarborgen.
• Geef de taal op direct na de opening backticks voor syntaxisverlichting (bijvoorbeeld ``````python).
• Gebruik inline code voor korte fragmenten of opdrachten binnen tekst.
• Vermijd ingewikkelde codeblokken tenzij het nodig is voor compatibiliteit met oudere systemen, omdat ze geen syntaxisverlichting ondersteunen en minder leesbaar zijn.
• Plaats een lege regel voor en na ongewone codeblokken om leesbaarheid in ruwe Markdown te verbeteren.

Speciale functies

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

Uitkomst

Gebruik ongewone codeblokken met een taalidentificatie voor de beste leesbaarheid en syntaxisverlichting. Reserveer inline code voor korte fragmenten en vermijd ingewikkelde blokken tenzij het nodig is voor compatibiliteit.

Diff syntaxisverlichting

Om diff syntaxisverlichting effectief te gebruiken in Markdown codeblokken, volg dan deze stappen:

• Gebruik ongewone codeblokken met drievoudige backticks (```) om je blok te beginnen en te eindigen.
• Geef diff op als taalidentificatie direct na de opening backticks. Dit activeert syntaxisverlichting voor verschillen, vergelijkbaar met wat je ziet in Git commitberichten of pull requests.

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:

• Gebruik dit formaat om codeveranderingen, correcties of suggesties duidelijk te communiceren in documentatie, codebeoordelingen of technische blogs.
• Plaats een lege regel voor en na je codeblok voor betere leesbaarheid in ruwe Markdown.
• Merk op dat diff-verlichting alleen hele regels kleurt op basis van het leidende karakter; het ondersteunt geen inline veranderingen binnen een regel.

Tip:
Deze methode wordt breed ondersteund op platforms zoals GitHub, GitLab en veel Markdown-afbeelders, waardoor het een betrouwbaar keuze is voor het visueel delen van codeveranderingen.

Ondersteunde talen

Markdown codeblokken ondersteunen een brede variëteit van talen voor syntaxisverlichting, maar de exacte set van ondersteunde talen hangt af van de afbeeldaar of het platform dat je gebruikt. Markdown zelf definieert niet welke talen ondersteund worden; het geeft gewoon de taalidentificatie door aan de afbeeldingsmotor, die dan de juiste syntaxisverlichting toepast. Markdown codeblokken zelf definiëren geen vaste lijst van officieel ondersteunde programmeertalen. In plaats daarvan hangt de lijst van ondersteunde talen af van de Markdown-afbeeldaar of het platform dat je gebruikt (zoals GitHub, GitLab, VS Code, Typora, Quarto, enz.).

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

• Web & Scripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programmeren: python (py), java, c, c++, 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: Gebruik de taal naam direct na de opening drievoudige backticks:

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

De volgende talen worden breed ondersteund op MEESTE Markdown-afbeelders:

Opmerking: De werkelijke identificatie kan variëren (bijvoorbeeld js versus javascript). De meeste afbeelders zijn niet gevoelig voor hoofdletters in taal namen.

Het vinden van de volledige lijst van ondersteunde talen:

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

Belangrijke punten:

• De meeste platforms ondersteunen alle belangrijke programmeertalen, scripttalen en markup talen.
• Sommige platforms ondersteunen ook diagrammen en dataformaten (zoals mermaid, geojson).
• De taalidentificatie is meestal niet gevoelig voor hoofdletters, maar moet in kleine letters zijn voor de beste compatibiliteit.
• Als je een niet-ondersteunde taalidentificatie gebruikt, wordt het codeblok weergegeven als platte tekst.

Het opgeven van een bestandsnaam in een Markdown codeblok

Om een bestandsnaam op te geven in een Markdown codeblok, heb je verschillende opties, maar de methode hangt af van het platform en de afbeeldaar:

1. Bestandsnaam in de Codebloklabel (Meta Syntax)

Sommige Markdown-afbeelders (zoals bepaalde statische sitegeneratoren, documentatie-tools en blogplatforms) ondersteunen een meta syntax waarbij je de bestandsnaam toevoegt na de taal, gescheiden door een dubbelepunt:

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

Dit zal de bestandsnaam (bijvoorbeeld app.js) tonen boven of naast het codeblok, afhankelijk van de afbeeldaar. En deze website’ hugo afbeeldaar doet dat niet:

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

Opmerking: Dit wordt niet ondersteund op alle platforms (bijvoorbeeld GitHub-flavored Markdown ondersteunt dit momenteel niet).

2. Manuele bestandsnaamkop of inline code

Voor universele compatibiliteit (inclusief GitHub, Stack Overflow en meeste Markdown-afbeelders), plaats de bestandsnaam boven het codeblok, met behulp van een kop of vetgedrukte inline code:

**`app.js`**

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

Of:

#### `app.js`

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

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

3. Bestandsnaam als commentaar in de code

Alternatief kun je de bestandsnaam als commentaar binnen het codeblok zelf opnemen:

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

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

Samenvatting en beste praktijk

Gebruik een kop of vetgedrukte inline code boven het codeblok voor maximale compatibiliteit, en overweeg een commentaar binnen de code voor duidelijkheid wanneer je het deelt over verschillende platforms.

Nuttige links

• Markdown Cheatsheet - Meest nuttige structuren en opdrachten
• Hugo Cheat Sheet
• Bash Cheat Sheet - Meest nuttige bash opdrachten
• LaTeX Cheat Sheet
• Meest populaire thema’s voor Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks