Markdown-kodblock - Snabbguide och exempel på hur man använder

Här granskar jag Codeblock-alternativ i Markdown. Hur man anger programmeringsspråk, diff-formatering och filnamn i kodblock.

Markdown codeblocks

Markdown codeblocks är ett sätt att visa kod eller förformaterad text inom Markdown-dokument, medan formateringen bevaras och syntaxmarkering möjliggörs. Det finns två huvudtyper av kodformatering i Markdown: inline-kod och kodblock.

Typer av Markdown kodblock

Viktiga skillnader

• Inline-kod använder enkla backticks (`) och är för kort kod inom en mening.
• Indenterade kodblock använder fyra mellanslag eller en tabb i början av varje rad. De stöder inte syntaxmarkering och är mindre vanliga i modern Markdown.
• Avgränsade kodblock använder tripla backticks (```) eller tildar (~~~) före och efter koden. Detta är det föredragna sättet, särskilt på plattformar som GitHub, eftersom:
  • De är lättare att läsa och skriva.
  • Du kan ange programmeringsspråket direkt efter de öppnande backticks för syntaxmarkering.
  • De bevarar formateringen och stöder multi-radig kod.

Exempel på ett avgränsat kodblock med syntaxmarkering:

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

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

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

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

Bästa praxis för användning av Markdown kodblock

• Använd avgränsade kodblock (tripla backticks) för multi-radig kod för att säkerställa klarhet och kompatibilitet över plattformar.
• Ange språket efter de öppnande backticks för syntaxmarkering (t.ex., ``````python).
• Använd inline-kod för korta kodsnuttor eller kommandon inom text.
• Undvik indenterade kodblock om inte nödvändigt för bakåtkompatibilitet, eftersom de inte stöder syntaxmarkering och kan vara mindre läsbara.
• Placera en tom rad före och efter avgränsade kodblock för att förbättra läsbarheten i rå Markdown.

Specialfunktioner

• Vissa plattformar stöder ytterligare språkidentifierare som diff för att visa kodändringar, vilket kan markera tillagda eller borttagna rader i kodgranskningar.
• För att visa backticks inom ett kodblock, wrapa blocket i ett högre antal backticks (t.ex., fyra backticks för att visa tre backticks).

Sammanfattning

Använd avgränsade kodblock med en språkidentifierare för bäst läsbarhet och syntaxmarkering. Reservera inline-kod för korta kodsnuttor och undvik indenterade block om inte nödvändigt för kompatibilitet.

Diff syntaxmarkering

För att effektivt använda diff syntaxmarkering i Markdown kodblock, följ dessa steg:

• Använd avgränsade kodblock med tripla backticks (```) för att starta och avsluta ditt block.
• Ange diff som språkidentifierare direkt efter de öppnande backticks. Detta aktiverar syntaxmarkering för skillnader, liknande vad du ser i Git-commit-meddelanden eller pull requests.

Exempel:

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

• Rader som börjar med - kommer att markeras som borttagningar (vanligtvis röd).
• Rader som börjar med + kommer att markeras som tillägg (vanligtvis grön).
• Rader utan prefix kommer inte att särskilt markeras.

Bästa praxis:

• Använd detta format för att tydligt kommunicera kodändringar, korrigeringar eller förslag i dokumentation, kodgranskningar eller tekniska bloggar.
• Placera en tom rad före och efter ditt kodblock för bättre läsbarhet i rå Markdown.
• Observera att diff-markering endast färgar hela rader baserat på det ledande tecknet; det markerar inte ändringar inom en rad.

Tips: Denna metod stöds bredt på plattformar som GitHub, GitLab och många Markdown-renderare, vilket gör den till ett pålitligt val för att dela kodändringar visuellt.

Stödda språk

Markdown kodblock stöder en mängd olika språk för syntaxmarkering, men den exakta listan över stödda språk beror på renderaren eller plattformen du använder. Markdown i sig definierar inte vilka språk som stöds; det skickar bara språkidentifieraren till renderingsmotorn, som sedan tillämpar lämplig syntaxmarkering. Markdown kodstängsel definierar inte en fast uppsättning officiellt stödda programmeringsspråk. Istället beror listan över stödda språk på Markdown-renderaren eller plattformen du använder (t.ex. GitHub, GitLab, VS Code, Typora, Quarto etc.).

Vanligt stödda språk på stora plattformar (t.ex. GitHub, VS Code, Bitbucket, Docusaurus och ReadMe) inkluderar:

• Webb & Skript: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programmering: python (py), java, c, c++, 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)
• Andra: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme och många fler

Hur man anger ett språk: Använd språknamnet direkt efter de öppnande tripla backticks:

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

Följande språk stöds bredt över MOST Markdown-renderare:

Anteckning: Den faktiska identifieraren kan variera (t.ex., js vs. javascript). De flesta renderare är case-insensitive för språknamn.

Hur man hittar den fullständiga listan över stödda språk:

• GitHub: Använder Linguist för markering, stöder hundratals språk.
• VS Code & många webrenderare: Använder highlight.js eller Pygments—se deras dokumentation för utförliga listor.
• Bitbucket: Refererar till CodeMirror modes och Pygments lexers.

Viktiga punkter:

• De flesta plattformar stöder alla stora programmerings-, skript- och markup-språk.
• Vissa plattformar stöder också diagram- och dataformat (t.ex. mermaid, geojson).
• Språkidentifieraren är vanligtvis case-insensitive men bör vara i gemener för bäst kompatibilitet.
• Om du använder en icke-stödd språkidentifierare, kommer kodblocket att renderas som vanlig text.

Angivande av filnamn i Markdown kodblock

För att ange ett filnamn i ett Markdown kodblock, har du flera alternativ, men metoden beror på plattformen och renderaren:

1. Filnamn i Kodblockets Etikett (Meta-syntax)

Vissa Markdown-motorer (t.ex. vissa statiska webbplatsgenererare, dokumentationsverktyg och bloggplattformar) stöder en meta-syntax där du lägger till filnamnet efter språket, separerat av ett kolon:

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

Detta kommer att visa filnamnet (t.ex., app.js) ovanför eller bredvid kodblocket, beroende på renderaren. Och denna webbplats hugo-renderare gör inte det:

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

Anteckning: Detta stöds inte på alla plattformar (t.ex. stöder GitHub-flavored Markdown inte denna funktion).

2. Manuellt Filnamn Rubrik eller Inline-kod

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

**`app.js`**

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

Eller:

#### `app.js`

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

Detta associerar visuellt filnamnet med kodblocket och fungerar överallt.

3. Filnamn som en Kommentar i Koden

Alternativt kan du inkludera filnamnet som en kommentar inom kodblocket självt:

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

Detta är särskilt användbart om du vill att filnamnet ska vara synligt när koden kopieras.

Sammanfattning och bästa praxis

Använd en rubrik eller fet inline-kod ovanför kodblocket för maximal kompatibilitet, och överväg att lägga till en kommentar inom koden för klarhet när du delar över olika plattformar.

Användbara länkar

• Markdown Cheatsheet - De mest användbara strukturerna och kommandon
• Hugo Cheat Sheet
• Bash Cheat Sheet - De mest användbara bash-kommandon
• LaTeX Cheat Sheet
• De mest populära temana för Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks