Markdown-kodblock: En komplett guide med syntax, språk och exempel

Här granskar jag alternativ för kodblok i Markdown – hur man specificerar programmeringsspråk, formaterar diff och anger filnamn i kodblok.

Den här guiden är en del av vår hubb för Dokumentationsverktyg 2026: Markdown, LaTeX, PDF och arbetsflöden för utskrift.

Översikt över kodblok i Markdown

Kodblok i Markdown visar kod eller förformaterad text inom Markdown-dokument, vilket bevarar formateringen och valfritt möjliggör syntaxmarkering. Det finns två huvudtyper av kodformatering i Markdown: inline-kod och kodblok.

Typer av kodblok i Markdown

Viktiga skillnader

• Inline-kod använder enkla backticks (`) och avses för kort kod mitt i en mening.
• Indenterade kodblok använder fyra mellanslag eller ett tabuleringstecken i början av varje rad. De stöder inte syntaxmarkering och är ovanliga i modern Markdown.
• Avgränsade kodblok använder trippelbackticks (```) eller tilde (~~~) före och efter koden. Detta är den föredragna metoden, särskilt på plattformar som GitHub, eftersom:
  • De är lättare att läsa och skriva.
  • Du kan specificera programmeringsspråket direkt efter de öppnande backtickarna för syntaxmarkering.
  • De bevarar formateringen och stöder flerradskod.

Exempel på en avgränsad kodblok med syntaxmarkering:

När vi har följande Markdown-formaterad text:

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

Så ser den renderade utmatningen ut så här:

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

Bästa praxis för kodblok i Markdown

• Använd avgränsade kodblok (trippelbackticks) för flerradskod för att säkerställa tydlighet och kompatibilitet över plattformar.
• Specificera språket efter de öppnande backtickarna för syntaxmarkering (t.ex. ```python).
• Använd inline-kod för korta klipp eller kommandon i texten.
• Undvik indenterade kodblok om det inte krävs för bakåtkompatibilitet, eftersom de inte stöder syntaxmarkering och kan vara svårare att läsa.
• Placera en tom rad före och efter avgränsade kodblok för att förbättra läsbarheten i rå Markdown.

Specialfunktioner

• Vissa plattformar stöder ytterligare språkidentifikatorer som diff för att visa kodändringar, vilket markerar tillagda eller borttagna rader vid kodgranskning.
• För att visa backticks inuti en kodblok, kapsla blokken i ett högre antal backticks (t.ex. fyra backticks för att visa tre backticks inuti).

Snabbreferenssammanfattning

Använd avgränsade kodblok med en språkidentifikator för bästa läsbarhet och syntaxmarkering. Använd inline-kod för korta klipp och undvik indenterade blok om det inte är nödvändigt för kompatibilitetens skull.

Kodblok passar naturligt med tabeller i Markdown för att skapa välstrukturerad teknisk dokumentation.

Diff-syntaxmarkering

Diff-syntaxmarkering låter dig visa kodändringar tydligt – användbart i dokumentation, kodgranskning och tekniska bloggar.

• Använd avgränsade kodblok med trippelbackticks (```) för att starta och avsluta din blok.
• Specificera diff som språkidentifikator direkt efter de öppnande backtickarna.

Exempel:

- gammal rad som ska tas bort
+ ny rad som ska läggas till
  oförändrad rad

• Rader som börjar med - markeras som raderingar (vanligtvis rött).
• Rader som börjar med + markeras som tillägg (vanligtvis grönt).
• Rader utan prefix markeras inte särskilt.

Bästa praxis:

• Placera en tom rad före och efter din kodblok för bättre läsbarhet i rå Markdown.
• Observera att diff-markering bara färgar hela rader baserat på det ledande tecknet; den markerar inte ändringar inline inom en rad.

Tips: Diff-markering stöds brett på GitHub, GitLab och de flesta Markdown-renderare, vilket gör det till ett pålitligt val för att kommunicera kodändringar.

Stöd för språk för syntaxmarkering

Det exakta utbudet av stödda språk beror på den renderare eller plattform du använder. Markdown skickar språkidentifikatorn till renderingmotorn, som tillämpar lämplig syntaxmarkering. Detta är viktigt vid konvertering av HTML till Markdown med Python, eftersom <code>-taggar som bär språk-klassattribut (t.ex. class="language-python") avbildas direkt till dessa identifikatorer i den avgränsade blokken.

Vanligt stödda språk på större plattformar (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe):

• Webb & Skript: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programmering: python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• Data & Frågor: sql, r, matlab
• Markup & Konfiguration: markdown, ini, toml, dockerfile, makefile
• Special: diff, mermaid, geojson, topojson, stl (för diagram och datavisualiseringar på GitHub) – mermaid-identifikatorn möjliggör i synnerhet fullständig diagramrendering på stödda plattformar; se Mermaid-diagram: Snabbstart och minnesanteckningar för en komplett syntaxreferens och Hugo-inställningsguide
• Övriga: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme och många fler

Hur man specificerar ett språk:

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

Språkidentifikatorer som stöds över de flesta renderare:

Observera: De flesta renderare är skiftlägeskänsliga för språknamn. Om du använder en icke-stödd identifikator renderas kodblokken som vanlig text.

Att hitta den fullständiga listan över stödda språk:

• GitHub: Använder Linguist, som stödjer hundratals språk.
• VS Code & många webbrenderare: Använder highlight.js eller Pygments – se deras dokumentation för utförliga listor.
• Bitbucket: Hänvisar till CodeMirror modes och Pygments-lexers.

Specificera ett filnamn i en Markdown-kodblok

Att visa filnamnet tillsammans med en kodblok hjälper läsarna att identifiera vilken fil ett klipp tillhör. Stödet varierar mellan plattformar.

1. Filnamn i kodblokens etikett (Meta-syntax)

Vissa Markdown-motorer (vissa statiska webbplatsgeneratorer och dokumentationsplattformar) stöder en meta-syntax där du lägger till filnamnet efter språket, separerat med ett kolon:

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

Detta visar filnamnet ovanför eller bredvid kodblokken. Denna webbplatsens Hugo-renderare stöder det inte:

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

Observera: Detta stöds inte i GitHub-flavored Markdown.

2. Manuell rubrik eller inline-kod för filnamn

För universell kompatibilitet (inklusive GitHub, Stack Overflow och de flesta Markdown-renderare), placera filnamnet ovanför kodblokken med fet inline-kod:

**`app.js`**

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

Eller med en rubrik:

#### `app.js`

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

Detta fungerar överallt och associerar visuellt filnamnet med kodblokken.

3. Filnamn som kommentar inuti koden

Inkludera filnamnet som en kommentar inuti själva kodblokken:

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

Detta är särskilt användbart när du vill att filnamnet ska vara synligt vid kopiering av koden.

Kompatibilitetssammanfattning

Använd fet inline-kod ovanför kodblokken för maximal kompatibilitet, och överväg en kommentar inuti koden för tydlighet vid delning över plattformar.

Escape av backticks inuti kodblok

För att visa backtick-avgränsningar inuti en kodblok – till exempel när man skriver dokumentation om Markdown självt – kapsla blokken i ett högre antal backticks:

````markdown
```python
# Denna trippelbacktick-avgränsning är inuti en fyra-backtick-avgränsning
print("hello")
```
````

Att använda fyra backticks som den yttre avgränsningen låter dig visa exempel med trippelbackticks inuti, vilket är praktiskt för Markdown-tutorials och minnesanteckningar.

Hugo-specifikt: Highlight-shortcoden

Om du använder Hugo erbjuder den inbyggda highlight-shortcoden mer kontroll än enkla avgränsade blok, inklusive radnummer och markerade rader:

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

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

Alternativ:

• linenos=true – visa radnummer
• hl_lines=2 4 – markera rad 2 och 4
• linenostart=10 – starta radnumreringen vid 10

Detta är särskilt användbart i tutorials eller dokumentation där du vill dra uppmärksamheten till specifika rader. Se Markdown-minnesanteckningar för fler formateringsfunktioner, och Hugo-minnesanteckningar för en bredare referens för Hugo-kommandon och mallar.

Användbara länkar

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