Bloki kodu Markdown: Kompletny przewodnik po składni, językach i przykładach

W tym artykule omawiam opcje bloków kodu w Markdown — jak określić język programowania, formatowanie diff oraz nazwę pliku w bloku kodu.

Ten przewodnik jest częścią naszego centrum wiedzy Narzędzia do tworzenia dokumentacji w 2026 roku: Markdown, LaTeX, PDF i przepływy pracy drukowej.

Przegląd bloków kodu w Markdown

Bloki kodu w Markdown służą do wyświetlania kodu lub sformatowanego tekstu w dokumentach Markdown, zachowując formatowanie i opcjonalnie umożliwiając podświetlanie składni. W Markdown istnieją dwa główne typy formatowania kodu: kod inline i bloki kodu.

Typy bloków kodu w Markdown

Kluczowe różnice

• Kod inline używa pojedynczych apostrofów kodu (`) i służy do krótkiego kodu wewnątrz zdania.
• Bloki kodu wcięte używają czterech spacji lub tabulatora na początku każdego wiersza. Nie obsługują podświetlania składni i są mało popularne w nowoczesnym Markdown.
• Bloki kodu z ogrodzeniem (fenced) używają potrójnych apostrofów kodu (```) lub tyld (~~~) przed i po kodzie. Jest to zalecana metoda, szczególnie na platformach takich jak GitHub, ponieważ:
  • Są łatwiejsze do odczytu i pisania.
  • Można określić język programowania bezpośrednio po otwierających apostrofach kodu, aby włączyć podświetlanie składni.
  • Zachowują formatowanie i obsługują wielowierszowy kod.

Przykład bloku kodu z ogrodzeniem z podświetlaniem składni:

Gdy mamy następujący tekst sformatowany w Markdown:

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

Wygenerowany wynik wygląda następująco:

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

Najlepsze praktyki dotyczące bloków kodu w Markdown

• Używaj bloków kodu z ogrodzeniem (potrójne apostrofy kodu) do wielowierszowego kodu, aby zapewnić klarowność i kompatybilność między platformami.
• Określ język po otwierających apostrofach kodu dla podświetlania składni (np. ```python).
• Używaj kodu inline do krótkich fragmentów lub komend w tekście.
• Unikaj bloków kodu wciętych, chyba że są wymagane ze względu na kompatybilność z legacy, ponieważ nie obsługują podświetlania składni i mogą być mniej czytelne.
• Umieszczaj pusty wiersz przed i po blokach kodu z ogrodzeniem, aby poprawić czytelność w surowym Markdown.

Specjalne funkcje

• Niektóre platformy obsługują dodatkowe identyfikatory języków, takie jak diff do wyświetlania zmian w kodzie, co podświetla dodane lub usunięte linie podczas przeglądania kodu.
• Aby wyświetlić apostrofy kodu wewnątrz bloku kodu, otocz blok większą liczbą apostrofów kodu (np. czterema apostrofami kodu, aby wyświetlić trzy apostrofy kodu wewnątrz).

Krótkie podsumowanie

Używaj bloków kodu z ogrodzeniem z identyfikatorem języka dla najlepszej czytelności i podświetlania składni. Zarezerwuj kod inline do krótkich fragmentów i unikaj bloków wciętych, chyba że jest to konieczne ze względu na kompatybilność.

Bloki kodu naturalnie łączą się z tabelami w Markdown, aby tworzyć dobrze ustrukturyzowaną dokumentację techniczną.

Podświetlanie składni diff

Podświetlanie składni diff pozwala na wyraźne pokazanie zmian w kodzie — jest przydatne w dokumentacji, przeglądach kodu i blogach technicznych.

• Używaj bloków kodu z ogrodzeniem z potrójnymi apostrofami kodu (```) do rozpoczęcia i zakończenia bloku.
• Określ diff jako identyfikator języka bezpośrednio po otwierających apostrofach kodu.

Przykład:

- stara linia, która zostanie usunięta
+ nowa linia, która zostanie dodana
  niezmieniona linia

• Linie zaczynające się od - są podświetlane jako usunięcia (zazwyczaj na czerwono).
• Linie zaczynające się od + są podświetlane jako dodania (zazwyczaj na zielono).
• Linie bez prefiksu nie są specjalnie podświetlane.

Najlepsze praktyki:

• Umieszczaj pusty wiersz przed i po bloku kodu dla lepszej czytelności w surowym Markdown.
• Należy pamiętać, że podświetlanie diff koloruje tylko całe linie w oparciu o wiodący znak; nie podświetla zmian inline wewnątrz linii.

Wskazówka: Podświetlanie diff jest szeroko obsługiwane na GitHub, GitLab i większości renderów Markdown, co czyni je niezawodnym wyborem do komunikowania zmian w kodzie.

Obsługiwane języki do podświetlania składni

Dokładny zestaw obsługiwanych języków zależy od rendera lub platformy, której używasz. Markdown przekazuje identyfikator języku do silnika renderowania, który stosuje odpowiednie podświetlanie składni. Ma to znaczenie przy konwertowaniu HTML do Markdown przy użyciu Pythona, ponieważ znaczniki <code> z atrybutami klasy języka (np. class="language-python") mapują się bezpośrednio na te identyfikatory w bloku z ogrodzeniem.

Najczęściej obsługiwane języki na głównych platformach (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe):

• Web & Skrypty: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programowanie: python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• Dane & Zapytania: sql, r, matlab
• Markup & Konfiguracja: markdown, ini, toml, dockerfile, makefile
• Specjalne: diff, mermaid, geojson, topojson, stl (do diagramów i wizualizacji danych na GitHub) — identyfikator mermaid w szczególności umożliwia pełne renderowanie diagramów na obsługiwanych platformach; zobacz Szybki start i arkusz śródowy dla diagramów Mermaid dla pełnego odniesienia do składni i przewodnika po konfiguracji Hugo
• Inne: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme i wiele więcej

Jak określić język:

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

Identyfikatory języków obsługiwane przez większość renderów:

Uwaga: Większość renderów nie rozróżnia wielkości liter w nazwach języków. Jeśli użyjesz nieobsługiwanego identyfikatora, blok kodu zostanie wyświetlony jako zwykły tekst.

Jak znaleźć pełną listę obsługiwanych języków:

• GitHub: Używa Linguist, obsługując setki języków.
• VS Code & wiele renderów webowych: Używają highlight.js lub Pygments — zobacz ich dokumentację w celu uzyskania wyczerpujących list.
• Bitbucket: Odnosi się do trybów CodeMirror i leksykonów Pygments.

Określanie nazwy pliku w bloku kodu Markdown

Wyświetlanie nazwy pliku obok bloku kodu pomaga czytelnikom zidentyfikować, do którego pliku należy dany fragment. Obsługa różni się w zależności od platformy.

1. Nazwa pliku w etykiecie bloku kodu (Składnia meta)

Niektóre silniki Markdown (pewne generatory stron statycznych i platformy dokumentacyjne) obsługują składnię meta, w której dołączasz nazwę pliku po języku, oddzieloną dwukropkiem:

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

Wyświetla to nazwę pliku powyżej lub obok bloku kodu. Render Hugo tej strony nie obsługuje tej funkcji:

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

Uwaga: Nie jest to obsługiwane w Markdown w stylu GitHub (GFM).

2. Ręczny nagłówek nazwy pliku lub kod inline

Dla uniwersalnej kompatybilności (w tym GitHub, Stack Overflow i większość renderów Markdown), umieść nazwę pliku powyżej bloku kodu, używając pogrubionego kodu inline:

**`app.js`**

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

Lub z nagłówkiem:

#### `app.js`

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

Działa to wszędzie i wizualnie łączy nazwę pliku z blokiem kodu.

3. Nazwa pliku jako komentarz w kodzie

Umieść nazwę pliku jako komentarz wewnątrz samego bloku kodu:

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

Jest to szczególnie przydatne, gdy chcesz, aby nazwa pliku była widoczna podczas kopiowania kodu.

Podsumowanie kompatybilności

Używaj pogrubionego kodu inline powyżej bloku kodu dla maksymalnej kompatybilności, a rozważ komentarz wewnątrz kodu dla klarowności przy udostępnianiu między platformami.

Escapowanie apostrofów kodu wewnątrz bloków kodu

Aby wyświetlić ogrodzenia apostrofów kodu wewnątrz bloku kodu — np. przy pisaniu dokumentacji o samym Markdown — zagnieźdź blok w większej liczbie apostrofów kodu:

````markdown
```python
# To ogrodzenie z potrójnych apostrofów kodu jest wewnątrz ogrodzenia z czterech apostrofów kodu
print("hello")
```
````

Użycie czterech apostrofów kodu jako zewnętrznego ogrodzenia pozwala na pokazanie przykładów z potrójnymi apostrofami kodu wewnątrz, co jest przydatne w samouczkach i arkuszach śródowych Markdown.

Specyficzne dla Hugo: Shortcode Highlight

Jeśli używasz Hugo, wbudowany shortcode highlight oferuje większą kontrolę niż zwykłe bloki z ogrodzeniem, w tym numery linii i podświetlane linie:

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

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

Opcje:

• linenos=true — pokaż numery linii
• hl_lines=2 4 — podświetl linie 2 i 4
• linenostart=10 — rozpocznij numerowanie linii od 10

Jest to szczególnie przydatne w samouczkach lub dokumentacji, gdzie chcesz zwrócić uwagę na konkretne linie. Zobacz Arkusz śródowy Markdown po więcej funkcji formatowania oraz Arkusz śródowy Hugo dla szerszego odniesienia do komend i szablonów Hugo.

Przydatne linki

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