Blok kodu w Markdown - cheat sheet i przykłady użycia

Oto recenzja opcji bloków kodu w Markdown.

Bloki kodu w Markdown

Blok kodu w Markdown to sposób na wyświetlanie kodu lub wstępnie sformatowanego tekstu w dokumentach Markdown, zachowując formatowanie i opcjonalnie włączając wyróżnienie składni. W Markdown są dwie główne formy formatowania kodu: kod wewnętrzny i bloki kodu.

Rodzaje bloków kodu w Markdown

Główne różnice

• Kod wewnętrzny używa pojedynczych backticków (`) i służy do krótkich fragmentów kodu wewnątrz zdania.
• Zagnieżdżone bloki kodu używają czterech spacji lub tabulacji na początku każdej linii. Nie obsługują wyróżnienia składni i są rzadziej używane w nowoczesnym Markdown.
• Blok ograniczony używa trzech backticków (```) lub znaków tildy (~~~) przed i po kodzie. Jest to preferowany sposób, szczególnie na platformach takich jak GitHub, ponieważ:
  • Są łatwiejsze do czytania i pisania.
  • Można natychmiast określić język programowania po otwartych backtickach w celu wyróżnienia składni.
  • Zachowują formatowanie i obsługują wieloliniowy kod.

Przykład bloku kodu ograniczonego z wyróżnieniem składni:

Kiedy mamy poniższy sformatowany tekst w Markdown:

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

Wtedy wyrenderowany tekst wygląda tak:

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

Najlepsze praktyki dotyczące użycia bloków kodu w Markdown

• Używaj bloków kodu ograniczonych (trzy backticky) dla wieloliniowego kodu, aby zapewnić przejrzystość i kompatybilność na różnych platformach.
• Określ język po otwartych backtickach w celu wyróżnienia 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 są wymagane dla kompatybilności z przeszłością, ponieważ nie obsługują wyróżnienia składni i mogą być mniej czytelne.
• Umieszczaj pustą linię przed i po blokach kodu ograniczonych, aby poprawić czytelność w surowym Markdown.

Specjalne funkcje

• Niektóre platformy obsługują dodatkowe identyfikatory języka, takie jak diff do pokazywania zmian w kodzie, które mogą wyróżniać dodane lub usunięte linie w recenzjach kodu.
• Aby wyświetlić backticky wewnątrz bloku kodu, otocz blok większą liczbą backticków (np. cztery backticky, aby wyświetlić trzy backticky).

Podsumowanie

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

Wyróżnienie składni diff w Markdown

Aby efektywnie używać wyróżnienia składni diff w blokach kodu Markdown, wykonaj następujące kroki:

• Używaj ograniczonych bloków kodu z trzema backtickami (```) do rozpoczęcia i zakończenia swojego bloku.
• Określ diff jako identyfikator języka natychmiast po otwartych backtickach. To włącza wyróżnienie różnic, podobnie jak w komunikatach commitów Git lub żądaniach pull.

Przykład:

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

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

Najlepsze praktyki:

• Używaj tego formatu, aby jasno komunikować zmiany w kodzie, naprawy lub sugestie w dokumentacji, recenzjach kodu lub technicznych blogach.
• Umieszczaj pustą linię przed i po swoim bloku kodu, aby poprawić czytelność w surowym Markdown.
• Zauważ, że wyróżnienie diff koloruje całe linie na podstawie znaku wiodącego; nie wyróżnia zmian wewnątrz linii.

Porada:
Ten sposób jest szeroko obsługiwany na platformach takich jak GitHub, GitLab i wielu rendererach Markdown, co czyni go niezawodnym wyborem do wizualnego dzielenia się zmianami w kodzie.

Obsługiwane języki

Blok kodu w Markdown obsługuje szeroki zakres języków do wyróżnienia składni, ale dokładna lista obsługiwanych języków zależy od renderera lub platformy, którą używasz. Markdown sam w sobie nie definiuje, które języki są obsługiwane; po prostu przekazuje identyfikator języka do silnika renderowania, który następnie stosuje odpowiednie wyróżnienie składni. Blok ograniczony w Markdown sam w sobie nie definiuje ustalonego zestawu oficjalnie obsługiwanych języków programowania. Zamiast tego lista obsługiwanych języków zależy od renderera Markdown lub platformy, którą używasz (np. GitHub, GitLab, VS Code, Typora, Quarto itp.).

Powszechnie obsługiwane języki na głównych platformach (takich jak GitHub, VS Code, Bitbucket, Docusaurus i ReadMe) obejmują:

• Sieci i skrypty: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programowanie: python (py), java, c, c++, 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: Użyj nazwy języka natychmiast po otwartych trzech backtickach:

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

Następujące języki są szeroko obsługiwane przez większość rendererów Markdown:

Uwaga: Rzeczywisty identyfikator może się różnić (np. js vs. javascript). Większość rendererów jest nieczuła na wielkość liter w nazwach języków.

Znalezienie pełnej listy obsługiwanych języków:

• GitHub: Używa Linguist do wyróżnienia, obsługując setki języków.
• VS Code i wiele rendererów internetowych: Używają highlight.js lub Pygments – zobacz ich dokumentację dla pełnych list.
• Bitbucket: Odwołuje się do trybów CodeMirror i leksykonów Pygments.

Główne punkty:

• Większość platform obsługuje wszystkie główne języki programowania, skryptowania i markowania.
• Niektóre platformy również obsługują formaty diagramów i danych (np. mermaid, geojson).
• Identyfikator języka jest zazwyczaj nieczuły na wielkość liter, ale powinien być małymi literami dla najlepszej kompatybilności.
• Jeśli używasz nieobsługiwanego identyfikatora języka, blok kodu zostanie wyrenderowany jako zwykły tekst.

Określanie nazwy pliku w bloku kodu Markdown

Aby określić nazwę pliku w bloku kodu Markdown, masz kilka opcji, ale metoda zależy od platformy i renderera:

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

Niektóre silniki Markdown (takie jak niektóre generatory statycznych stron internetowych, narzędzia dokumentacyjne i platformy blogowe) obsługują meta składnię, w której dodajesz nazwę pliku po języku, oddzieloną dwukropkiem:

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

To wyświetli nazwę pliku (np. app.js) nad lub obok bloku kodu, w zależności od renderera.
A jednak renderer Hugo tej strony nie obsługuje tego:

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

Uwaga: Ta funkcja nie jest obsługiwana na wszystkich platformach (np. GitHub-flavored Markdown nie obsługuje tej funkcji w chwili obecnej).

2. Rozdzielona nagłówek lub kod wewnętrzny

Dla uniwersalnej kompatybilności (w tym GitHub, Stack Overflow i większość rendererów Markdown), umieść nazwę pliku nad blokiem kodu, używając nagłówka lub pogrubionego kodu wewnętrznego:

**`app.js`**

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

Lub:

#### `app.js`

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

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

3. Nazwa pliku jako komentarz w kodzie

Alternatywnie możesz dołączyć nazwę pliku jako komentarz wewnątrz samego bloku kodu:

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

To jest szczególnie przydatne, jeśli chcesz, aby nazwa pliku była widoczna przy kopiowaniu kodu.

Podsumowanie i najlepsze praktyki

Używaj nagłówka lub pogrubionego kodu wewnętrznego nad blokiem kodu dla maksymalnej kompatybilności, a rozważ dodanie komentarza wewnątrz kodu dla przejrzystości przy udostępnianiu na różnych platformach.

Przydatne linki

• Przewodnik po Markdown - Najważniejsze struktury i polecenia
• Przewodnik po Hugo
• Przewodnik po Bash - Najważniejsze polecenia Bash
• Przewodnik po LaTeX
• Najpopularniejsze motywy dla Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks