Bloki Kodu Markdown: Kompletny Przewodnik z Sintaksem, Językami i Przykładami

Tu omawiam opcje bloków kodu w Markdown — jak określić język programowania, formatowanie różnic i nazwę pliku kodu.

Ten przewodnik jest częścią naszego Przewodnika po narzędziach dokumentacji w 2026: Markdown, LaTeX, PDF i przepływach pracy drukowania hub.

Omówienie bloków kodu w Markdown

Blokowe fragmenty kodu w Markdown wyświetlają kod lub wstępnie sformatowany tekst w dokumentach Markdown, zachowując formatowanie i opcjonalnie włączając wyróżnianie składni. W Markdown są dwie główne formy formatowania kodu: wewnętrzny kod i bloki kodu.

Rodzaje bloków kodu w Markdown

Główne różnice

• Wewnętrzny kod używa pojedynczych znaków odwrotnej apostrofy (`) i służy do krótkich fragmentów kodu wewnątrz zdania.
• Zagnieżdżone bloki kodu używają 4 spacji lub tabulacji na początku każdej linii. Nie wspierają wyróżniania składni i są rzadko używane w nowoczesnym Markdown.
• Zablokowane bloki kodu używają trzech znaków odwrotnej apostrofy (```) lub znaków ~ przed i po kodzie. Jest to preferowany sposób, szczególnie na platformach takich jak GitHub, ponieważ:
  • Są łatwiejsze do odczytania i pisania.
  • Można natychmiast określić język programowania po otwierających znakach odwrotnej apostrofy dla wyróżniania składni.
  • Zachowują formatowanie i wspierają wieloliniowy kod.

Przykład zablokowanego bloku kodu z wyróżnianiem składni:

Kiedy mamy poniższy tekst sformatowany w Markdown:

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

Wydrukowany wynik wygląda tak:

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

Najlepsze praktyki dotyczące bloków kodu w Markdown

• Używaj zablokowanych bloków kodu (trzy znaki odwrotnej apostrofy) dla wieloliniowego kodu, aby zapewnić przejrzystość i kompatybilność na różnych platformach.
• Określ język po otwierających znakach odwrotnej apostrofy dla wyróżniania składni (np. ```python).
• Używaj kodu wewnętrznego dla krótkich fragmentów lub poleceń w tekście.
• Unikaj zagnieżdżonych bloków kodu, chyba że wymagane są one dla kompatybilności z przeszłością, ponieważ nie wspierają wyróżniania składni i mogą być mniej czytelne.
• Umieszczaj pustą linię przed i po zablokowanym bloku kodu, aby poprawić czytelność w surowym Markdown.

Specjalne funkcje

• Niektóre platformy wspierają dodatkowe identyfikatory języka, takie jak diff do pokazywania zmian w kodzie, które wyróżniają dodane lub usunięte linie w recenzjach kodu.
• Aby wyświetlić znaki odwrotnej apostrofy wewnątrz bloku kodu, otocz blok większą liczbą znaków odwrotnej apostrofy (np. cztery znaki odwrotnej apostrofy do wyświetlenia trzech znaków odwrotnej apostrofy wewnątrz).

Szybki podsumowanie

Używaj zablokowanych bloków kodu z identyfikatorem języka dla najlepszej czytelności i wyróżniania składni. Rezerwuj wewnętrzny kod dla krótkich fragmentów, a unikaj zagnieżdżonych bloków, chyba że są one konieczne dla kompatybilności.

Blokowe fragmenty kodu naturalnie współgrają z tabelami w Markdown do budowania dobrze strukturyzowanej dokumentacji technicznej.

Wyróżnianie różnic składni

Wyróżnianie różnic składni pozwala wyraźnie pokazywać zmiany w kodzie — przydatne w dokumentacji, recenzjach kodu i technicznych blogach.

• Używaj zablokowanych bloków kodu z trzema znakami odwrotnej apostrofy (```) do rozpoczęcia i zakończenia bloku.
• Określ diff jako identyfikator języka bezpośrednio po otwierających znakach odwrotnej apostrofy.

Przykład:

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

• Linie zaczynające się od - są wyróżniane jako usunięcia (zwykle czerwone).
• Linie zaczynające się od + są wyróżniane jako dodania (zwykle zielone).
• Linie bez prefiksu nie są specjalnie wyróżniane.

Najlepsze praktyki:

• Umieszczaj pustą linię przed i po swoim bloku kodu dla lepszej czytelności w surowym Markdown.
• Zauważ, że wyróżnianie różnic koloruje całe linie na podstawie znaku wiodącego; nie wyróżnia zmian wewnątrz linii.

Porada: Wyróżnianie różnic jest szeroko wspierane na GitHub, GitLab i większości renderów Markdown, co czyni je wiarygodnym wyborem do komunikowania zmian w kodzie.

Wspierane języki dla wyróżniania składni

Dokładny zestaw wspieranych języków zależy od renderera lub platformy, którą używasz. Markdown przekazuje identyfikator języka do silnika renderowania, który stosuje odpowiednie wyróżnianie składni. To ma znaczenie, gdy konwertujesz HTML na Markdown w Pythonie, ponieważ <code> tagi zawierające atrybuty klas języka (np. class="language-python") mapują się bezpośrednio na te identyfikatory w zablokowanym bloku.

Powszechnie wspierane języki na głównych platformach (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe):

• Sieci i skryptowanie: 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 i zapytania: sql, r, matlab
• Markowanie i konfiguracja: markdown, ini, toml, dockerfile, makefile
• Specjalne: diff, mermaid, geojson, topojson, stl (dla diagramów i wizualizacji danych na GitHub)
• Inne: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme i wiele innych

Jak określić język:

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

Identyfikatory języka wspierane przez większość renderów:

Uwaga: Większość renderów jest nieczuła na wielkość liter w nazwach języków. Jeśli użyjesz nieobsługiwanego identyfikatora, blok kodu renderuje się jako zwykły tekst.

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

• GitHub: Używa Linguist, wspierając setki języków.
• VS Code i wiele renderów sieciowych: Używają highlight.js lub Pygments — zobacz ich dokumentację dla pełnej listy.
• Bitbucket: Odwołuje się do trybów CodeMirror i leksykonów Pygments.

Określanie nazwy pliku w bloku kodu w Markdown

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

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

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

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

To wyświetla nazwę pliku powyżej lub obok bloku kodu. Ten silnik renderujący Hugo nie wspiera tego:

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

Uwaga: Nie jest to wspierane w Markdownie z GitHub.

2. Ręczna nazwa pliku w nagłówku lub kodzie wewnętrznym

Dla uniwersalnej kompatybilności (w tym GitHub, Stack Overflow i większość renderów Markdown), umieszcz nazwę pliku powyżej bloku kodu za pomocą pogrubionego kodu wewnętrznego:

**`app.js`**

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

Lub z nagłówkiem:

#### `app.js`

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

To działa wszędzie i wizualnie łączy nazwę pliku z blokiem kodu.

3. Nazwa pliku jako komentarz wewnątrz kodu

Dodaj nazwę pliku jako komentarz wewnątrz samego bloku kodu:

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

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

Podsumowanie kompatybilności

Używaj pogrubionego kodu wewnętrznego powyżej bloku kodu dla maksymalnej kompatybilności, a rozważ komentarz wewnątrz kodu dla przejrzystości przy udostępnianiu na różnych platformach.

Ucieczka od znaków odwrotnej apostrofy wewnątrz bloków kodu

Aby wyświetlić znaki odwrotnej apostrofy wewnątrz bloku kodu — na przykład kiedy piszesz dokumentację o samym Markdown — zagnieżdżaj blok w większej liczbie znaków odwrotnej apostrofy:

````markdown
```python
# Ten zagnieżdżony znak odwrotnej apostrofy jest wewnątrz czterech znaków odwrotnej apostrofy
print("hello")
```
````

Użycie czterech znaków odwrotnej apostrofy jako zewnętrznego zagnieżdżenia pozwala Ci wyświetlić przykłady trzech znaków odwrotnej apostrofy wewnątrz, co jest przydatne w tutoriach i cheat sheetach Markdown.

Hugo-specyficzne: Krótkie kodowanie „highlight”

Jeśli używasz Hugo, wbudowany shortcode highlight oferuje większą kontrolę niż zwykłe zablokowane bloki, w tym numerowanie linii i wyróżnianie linii:

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

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

Opcje:

• linenos=true — pokazuje numerowanie linii
• hl_lines=2 4 — wyróżnia linie 2 i 4
• linenostart=10 — zaczyna numerowanie linii od 10

To jest szczególnie przydatne w tutoriach lub dokumentacji, gdzie chcesz zwrócić uwagę na konkretne linie. Zobacz cheat sheet Markdown dla więcej opcji formatowania, a także cheat sheet Hugo dla szerszego odniesienia do poleceń i szablonów Hugo.

Przydatne linki

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