GFM vs CommonMark vs Pandoc Markdown: porównanie składni

Markdown wygląda jak jeden język, dopóki ten sam plik nie wyrenderuje się inaczej w GitHub, Hugo, Obsidian lub Pandoc. A problem nie polega na tym, że Markdown jest niedostępny.

Problem polega na tym, że „Markdown” opisuje rodzinę powiązanych składni, parserów i funkcji platformowych, a nie jeden uniwersalny format dokumentu. CommonMark definiuje precyzyjne, przenośne jądro, GitHub Flavored Markdown dodaje funkcje przydatne do współpracy w projektach oprogramowania, a Pandoc Markdown rozszerza ten język na poważny format tworzenia dokumentów.

Wybór między nimi zależy od tego, gdzie dokument musi zostać wyświetlony. Plik README, artykuł w blogu Hugo i praca naukowa mają różne wymagania. To porównanie jest częścią szerszego narzędzi dokumentacyjnych obrazu i obejmuje formalne dialekty, rozszerzenia specyficzne dla platform oraz praktyczne zasady przenośności, aby można było wybrać właściwą składnię dla docelowego środowiska. W celu szybkiego zapoznania się ze składnią, ściągawka Markdown obejmuje podstawowe elementy formatowania.

Markdown to nie jeden język

Oryginalna składnia Markdown była celowo mała i luźno specyfikowana. Sprawiało to, że była łatwa w czytaniu i implementacji, ale różne parsery zaczęły interpretować niejednoznaczne dane wejściowe inaczej.

CommonMark został stworzony, aby zdefiniować spójne zasady parsowania dla fundamentalnych struktur Markdown. GitHub Flavored Markdown, zwykle nazywany GFM, opiera się na tej podstawie, dodając kilka powszechnie używanych rozszerzeń.

Pandoc Markdown podejmuje inną drogę. Zamiast pozostać małą składnią skierowaną na web, dodaje funkcje dokumentowe, takie jak cytowania, metadane, przypisy dolne, listy definicyjne, atrybuty i notacja matematyczna.

Uproszczony związek wygląda następująco:

Ta hierarchia jest przydatna, ale nie jest dokładnym dziedziczeniem w każdej implementacji. Każdy renderer może niezależnie włączać, wyłączać lub dodawać składnię.

Krótka odpowiedź

Używaj składni zgodnej z CommonMark, gdy przenośność ma największe znaczenie.

Używaj GFM, gdy piszesz pliki README, pull requesty, szablony zgłoszeń i dokumentację techniczną przeznaczoną głównie dla platform zgodnych z GitHub.

Używaj Pandoc Markdown, gdy dokument źródłowy musi zostać przekonwertowany na PDF, DOCX, EPUB, LaTeX, slajdy lub pracę akademicką z cytowaniami i metadanymi.

Dla technicznego bloga Hugo używaj jądra CommonMark oraz rozszerzeń Goldmark, które Twoja strona włącza wprost. Nie zakładaj, że każda funkcja widoczna w GitHub będzie działała tylko dlatego, że Hugo jest opisany jako zgodny z GFM.

Subiektywna opinia: jeśli zapamiętasz tylko jedną zasadę dla technicznego bloga Hugo, traktuj CommonMark oraz tabele i listy zadań w stylu GFM jako domyślny zestaw, a wszystko inne — przypisy dolne, matematyka, bloki informacyjne, atrybuty nagłówków — jako jawną, przetestowaną rozszerzenie, a nie domyślną funkcję. Ten pojedynczy nawyk zapobiega większości problemów z przenośnością opisanych poniżej.

CommonMark: Przenośne jądro

CommonMark jest formalną specyfikacją podstawowego języka Markdown. Głównym jego wkładem nie jest duży zbiór funkcji, ale spójne parsowanie.

Definiuje, jak parsery powinny interpretować:

• Akapity
• Nagłówki ATX i Setext
• Cytaty blokowe
• Listy uporządkowane i nieuporządkowane
• Blokady kodu z ogranicznikami i wcięte
• Wyróżnienie i mocne wyróżnienie
• Linki i obrazy
• Linki w stylu referencyjnym
• Kod inline
• Linie tematyczne (separatora)
• Surowe bloki HTML
• Twarde i miękkie łamania wierszy

Dokument CommonMark może nadal zachowywać się inaczej na warstwie prezentacji. CSS, podświetlanie składni, kotwice nagłówków, oczyszczanie HTML i polityki linków pozostają poza zasadami parsowania jądra.

CommonMark powinien więc być traktowany jako solidna strukturalna baza, a nie obietnica, że każdy renderer wygeneruje identyczną stronę.

Przenośny przykład CommonMark

# Service Deployment

The service exposes a small HTTP API.

## Requirements

- Linux
- Docker
- 8 GB of memory

## Start the service

```bash
docker compose up -d
```

See the [configuration guide](configuration.md) for details.

Tego typu dokument działa w praktycznie każdym nowoczesnym środowisku Markdown. Wykorzystuje nagłówki, akapity, listy, kod z ogranicznikami i zwykłe linki, nie polegając na rozszerzeniach specyficznych dla dialektu.

GitHub Flavored Markdown: CommonMark dla projektów oprogramowania

GitHub Flavored Markdown jest formalnym dialektem opartym na CommonMark. Zachowuje model parsowania CommonMark i dodaje funkcje często potrzebne w dokumentacji repozytoriów i współpracy.

Formalna specyfikacja GFM dodaje:

• Tabele z użyciem znaków pionowych (pipe tables)
• Elementy list zadań
• Przekreślenie
• Rozszerzone automatyczne linki (autolinks)
• Ograniczenia dotyczące niektórych surowych tagów HTML

Rozszerzenia te są teraz tak powszechne, że wielu użytkowników uważa je za część standardowego Markdown. Nie są one częścią jądra CommonMark.

Tabele GFM

| Backend | Best use |
|---|---|
| Ollama | Local experiments |
| vLLM | Shared inference |
| SGLang | Structured workloads |

Ściśle zgodny z CommonMark parser może potraktować to jako zwykły tekst akapitu. Parser zgodny z GFM rozpoznaje to jako tabelę. Aby poznać składnię tabel i opcje wyrównania, zobacz Tabele w Markdown.

Listy zadań GFM

- [x] Install Docker
- [x] Download the model
- [ ] Add monitoring

Składnia list zadań jest przydatna w zgłoszeniach (issues), pull requestach i dokumentacji projektowej. Poza renderującym narzędziem wspierającym tę funkcję, może ona pojawić się jako zwykła lista zawierająca dosłowne nawiasy kwadratowe.

Przekreślenie GFM

Use the ~~old endpoint~~ new endpoint.

Przekreślenie jest szeroko wspierane, ale nadal jest to rozszerzenie, a nie przenośna składnia CommonMark.

Automatyczne linki GFM

GFM rozpoznaje więcej tekstów przypominających URL-e i adresy e-mail, bez konieczności używania nawiasów kwadratowych lub jawnego składni linków.

Visit https://example.com/docs for details.

W ściśle CommonMark jawne automatyczne linki używają nawiasów kwadratowych:

<https://example.com/docs>

Jawna forma jest bezpieczniejsza, gdy dokument musi przejść przez nieznane procesory Markdown.

GitHub.com wspiera więcej niż formalny GFM

Częstym źródłem pomyłek jest założenie, że każda funkcja Markdown widoczna w GitHub należy do specyfikacji GFM.

Tak nie jest.

GitHub.com dodaje przetwarzanie i funkcje na poziomie platformy wokół parsera GFM. W zależności od kontekstu GitHub może wspierać:

• Wyrażenia matematyczne
• Diagramy Mermaid
• Alerty
• Odwołania do zgłoszeń i pull requestów
• Wspomnienia użytkowników i zespołów
• Odwołania do commitów
• Shortcode emoji
• Składane sekcje HTML
• Podglądy kolorów
• Linki względne do repozytorium
• Automatyczne kotwice nagłówków

Niektóre z tych funkcji to rozszerzenia składni. Inne to zachowanie przetwarzania poetycznego lub integracje z danymi GitHub.

Ta różnica ma znaczenie, ponieważ inny renderer może trafnie twierdzić zgodność z GFM, nie implementując jednak renderera matematyki GitHuba, integracji Mermaid, odwołań do zgłoszeń ani stylowania alertów.

Diagramy Mermaid w GitHub

GitHub renderuje blok kodu z ogranicznikami oznaczony jako mermaid jako diagram:

```mermaid
flowchart LR
    A[Markdown] --> B[Rendered diagram]
```

Uniwersalny renderer GFM może wyświetlić ten sam blok jako podświetlony kod źródłowy. Markdown pozostaje poprawny, ale rozszerzone renderowanie jest specyficzne dla platformy. Dla praktycznego wprowadzenia do składni Mermaid, zobacz Szybki start z diagramami Mermaid.

Wyrażenia matematyczne w GitHub

GitHub obsługuje wyrażenia matematyczne inline i blokowe za pomocą delimitatorów dolarów oraz dodatkowych form ucieczki.

The cache size is approximately $2nlhd$ bytes.

$$
C = 2nlhd
$$

Matematyka nie jest częścią formalnego GFM. Przenoszenie tej treści do innego renderera wymaga kompatybilnego rozszerzenia matematycznego, takiego jak KaTeX, MathJax lub wsparcie matematyki Pandoc.

Alerty w GitHub

GitHub obsługuje cytaty blokowe w stylu alertów, takie jak:

> [!WARNING]
> Changing this setting clears the cache.

W GitHubie może to wyglądać jak stylowane ostrzeżenie. W zwykłym renderze CommonMark zazwyczaj pojawia się jako zwykły cytat blokowy zawierający [!WARNING].

Ten fallback jest czytelny, co czyni alerty GitHuba mniej niebezpiecznymi niż rozszerzenia, które całkowicie znikają. Nadal nie są to jednak przenośne elementy prezentacji.

Pandoc Markdown: Markdown jako język dokumentu

Pandoc Markdown jest zaprojektowany do konwersji dokumentów, a nie dla jednej konkretnej strony internetowej. Używa Markdown jako składni źródłowej do tworzenia HTML, PDF, DOCX, EPUB, LaTeX, prezentacji i innych formatów.

Jego domyślny odczytywacz Markdown zawiera duży zestaw rozszerzeń. Ważne możliwości obejmują:

• Bloki metadanych YAML
• Przypisy dolne
• Cytowania
• Wiele formatów tabel
• Listy definicyjne
• Notację matematyczną
• Identyfikatory i atrybuty nagłówków
• Atrybuty bloków kodu
• Podzielone bloki z ogranicznikami (fenced divisions)
• Spany w nawiasach (bracketed spans)
• Indeksy górne i dolne
• Przekreślenie
• Bloki linii (line blocks)
• Numeryczne listy przykładów
• Surowy LaTeX
• Surowy HTML
• Automatyczne numerowanie sekcji
• Przetwarzanie bibliografii

Pandoc Markdown jest znacznie bardziej wyrazisty niż CommonMark lub formalny GFM. Ta wyrazistość czyni go potężnym w wydawnictwach, ale mniej bezpiecznym jako format wymiany.

Przypisy dolne w Pandoc

Markdown has several incompatible dialects.[^dialects]

[^dialects]: CommonMark, GFM, and Pandoc Markdown are three
    important examples.

Składnia przypisów dolnych jest wspierana przez wiele nowoczesnych narzędzi, ale nie jest częścią CommonMark ani formalnego GFM.

GitHub obecnie renderuje przypisy dolne w kilku kontekstach treści, ale jest to funkcja platformy GitHub, a nie formalna gwarancja GFM. Renderer twierdzący jedynie zgodność z CommonMark lub GFM może ich nie wspierać.

Cytowania w Pandoc

PagedAttention improves KV cache memory management
[@kwon2023pagedattention].

Z plikiem bibliografii i stylem cytowania, Pandoc może rozwiązać to w sformatowane cytowanie akademickie i bibliografię.

pandoc article.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -o article.pdf

Składnia cytowań pozostaje czytelna w renderze bez wsparcia, ale nie stanie się sformatowanym odwołaniem bez Pandoc lub innego kompatybilnego procesora cytowań. Elastność po stronie odczytywania w Pandoc wspiera również przepływy konwersji w drugą stronę — zobacz Konwersja dokumentów Word na Markdown jako praktyczny przykład użycia rozszerzonego dialektu Pandoc jako formatu pośredniego.

Listy definicyjne w Pandoc

CommonMark
: A precise specification for core Markdown.

GFM
: A CommonMark-based dialect with software-oriented extensions.

Pandoc Markdown
: An extended authoring format for document conversion.

Listy definicyjne są przydatne w instrukcjach, słownikach i książkach technicznych. Zazwyczaj źle degradują się w rendererach, które ich nie wspierają, ponieważ linie dwukropkowe pozostają widoczne jako zwykły tekst.

Atrybuty nagłówków w Pandoc

## Cache Configuration {#cache-config .deployment}

Pandoc interpretuje klamki jako jawne identyfikatory i listę klas. Wiele innych rendererów Markdown pokazuje tekst atrybutu bezpośrednio w nagłówku.

To jeden z najszybszych przykładów użytecznej składni, której nie należy umieszczać w dokumencie, który ma się renderować wszędzie.

Podzielone bloki w Pandoc

::: warning
Changing this option restarts the server.

Pandoc konwertuje to na strukturalny podział z klasą. Szablony, CSS, filtry lub moduły wyjściowe mogą zdecydować, jak ta struktura powinna wyglądać.

Większość rendererów CommonMark i GFM nie rozpoznaje ogranicznika. Wyświetlają dwukropki i zawartość jako zwykły tekst.

CommonMark vs GFM vs Pandoc Markdown

Poniższa macierz opisuje formalne dialekty, a nie każdą funkcję dodaną przez GitHub.com, Hugo, Obsidian, GitLab lub inną platformę.

Słowo „Nie” nie oznacza, że platforma nigdy nie może wspierać funkcji. Oznacza to, że funkcja nie jest gwarantowana przez formalną specyfikację tego dialektu.

Jaka składnia działa w GitHub?

Dla plików README, zgłoszeń (issues), pull requestów, dyskusji i wik, GFM jest naturalną bazą.

Można generalnie używać:

• Składni CommonMark
• Tabel
• List zadań
• Przekreślenia
• Rozszerzonych automatycznych linków
• Blok kodu z podświetleniem składni
• Odwołań specyficznych dla GitHub
• Matematyki wspieranej przez GitHub
• Diagramów wspieranych przez GitHub
• Alertów GitHub
• Przypisów dolnych, tam gdzie wspierane przez powierzchnię treści

Ryzyko przenośności zaczyna się, gdy GitHub wykonuje dodatkowe renderowanie wykraczające poza formalny GFM. Diagramy Mermaid, notacja matematyczna, odwołania do zgłoszeń i prezentacja alertów mogą nie przetrwać poza GitHub.

Dla plików repozytorium, które są również publikowane gdzie indziej, testuj źródło w drugim renderze, zamiast traktować podgląd GitHuba jako autorytatywny.

Jaka składnia działa w Hugo?

Hugo używa Goldmark jako domyślnego renderera Markdown. Goldmark jest zgodny z CommonMark i zapewnia rozszerzenia kompatybilne z istotnymi częściami GFM.

W typowej konfiguracji Hugo następujące elementy działają dobrze:

• Struktura CommonMark
• Bloki kodu z ogranicznikami
• Tabele z użyciem pipe
• Przekreślenie
• Listy zadań
• Automatyczne ID nagłówków
• Podświetlanie składni
• Przypisy dolne, gdy rozszerzenie jest włączone
• Listy definicyjne, gdy włączone
• Podmiany typograficzne, gdy włączone

Hugo dodaje również funkcje poza Markdown za pomocą:

• Metadanych front matter
• Shortcode
• Hooków renderowania
• Zasobów strony
• Funkcji referencji wewnętrznych
• Przetwarzania szablonów
• Konfiguracji strony

Te funkcje Hugo nie podróżują z plikiem Markdown. Dla praktycznego przykładu wdrożenia Hugo, zobacz Wdrożenie Hugo do AWS S3.

Front Matter w Hugo to nie treść Markdown

Strona Hugo często zaczyna się od metadanych YAML, TOML lub JSON:

---
title: "Markdown Compatibility"
description: "Compare Markdown dialects and renderers."
date: 2026-07-31
tags:
  - Markdown
  - documentation
---

Pandoc może również rozpoznawać bloki metadanych YAML, ale interpretuje pola zgodnie ze swoimi szablonami i modułami wyjściowymi. GitHub zazwyczaj wyświetla blok jako sekcję podobną do YAML lub traktuje go jako metadane repozytorium tylko w określonych systemach.

Ta sama składnia może więc być rozpoznawana w więcej niż jednym narzędziu, nie mając tych samych znaczeń.

Surowy HTML w Hugo

Goldmark nie renderuje potencjalnie niebezpiecznego surowego HTML w standardowej konfiguracji Hugo.

Blok taki jak:

<div class="notice">
  Restart the service after changing this value.
</div>

może zostać pominął, chyba że renderowanie surowego HTML jest włączone lub treść jest zaimplementowana za pomocą shortcode lub hook renderowania.

Dla kontrolowanego bloga technicznego włączenie surowego HTML może być uzasadnione. Nadal czyni to źródło mniej przenośnym i powinno być to świadoma decyzja na poziomie strony.

Mermaid w Hugo

Blok z ogranicznikami mermaid jest nadal zwykłym blokiem kodu, dopóki motyw Hugo, hook renderowania, shortcode lub potok JavaScript nie przekształci go w diagram.

GitHub i Hugo mogą więc akceptować identyczne źródło Mermaid, używając całkowicie różnych mechanizmów renderowania.

Jaka składnia działa w Pandoc?

Pandoc może czytać kilka dialektów Markdown jawne:

pandoc --from=markdown input.md
pandoc --from=commonmark input.md
pandoc --from=gfm input.md
pandoc --from=commonmark_x input.md

To jedna z najbardziej użytecznych funkcji przenośności Pandoc. Operator może powiedzieć Pandocowi, jaki dialekt stosuje źródło, zamiast polegać na niewyraźnym rozszerzeniu pliku .md.

Pandoc pozwala również włączać lub wyłączać poszczególne rozszerzenia:

pandoc \
  --from=markdown-footnotes-pipe_tables \
  input.md \
  -o output.html

Albo zacząć od węższego formatu i dodać jedną funkcję:

pandoc \
  --from=commonmark+footnotes \
  input.md \
  -o output.html

Można sprawdzić dostępne rozszerzenia za pomocą:

pandoc --list-extensions=markdown
pandoc --list-extensions=commonmark
pandoc --list-extensions=gfm

Ten model rozszerzeń jest potężny, ale oznacza to, że „Pandoc Markdown” nie zawsze jest jedną stałą konfiguracją. Polecenia budowania i pliki domyślnych ustawień są częścią specyfikacji dokumentu.

Jaka składnia działa w Obsidian?

Obsidian przechowuje notatki jako pliki Markdown, ale jego model tworzenia zawiera kilka funkcji specyficznych dla aplikacji.

Wspólnie przykłady obejmują:

• Linki Wiki
• Osadzone notatki
• Osadzone pliki
• Callouts
• Odwołania do bloków
• Tagi
• Właściwości (Properties)
• Wyróżnienia (Highlighting)
• Komentarze
• Zapytania Dataview z wtyczek
• Linki URI specyficzne dla aplikacji

Link Wiki, taki jak:

[[Markdown Compatibility]]

ma sens wewnątrz skarbca Obsidian. GitHub, CommonMark i domyślny odczytywacz Pandoc zwykle wyświetlają go jako dosłowny tekst w nawiasach kwadratowych.

Osadzanie jest jeszcze bardziej specyficzne dla aplikacji:

![[compatibility-table]]

Odwołana treść nie jest obecna w samym pliku. Eksportowanie lub publikowanie notatki wymaga więc etapu rozszerzania, który rozwiązuje osadzenie.

Obsidian jest dobrym przykładem dlaczego przechowywanie w plikach .md nie gwarantuje przenośności Markdown. Dla praktycznego spojrzenia na Obsidian jako narzędzie do zarządzania wiedzą, zobacz Obsidian do osobistego zarządzania wiedzą.

Jaka składnia działa w GitLab?

GitLab Flavored Markdown używa CommonMark jako jądra i zawiera funkcje GFM, takie jak tabele i listy zadań. Następnie dodaje zachowania specyficzne dla GitLab, w tym odwołania krzyżowe, notację matematyczną, diagramy i inne funkcje współpracy.

README napisany w konserwatywnym GFM zazwyczaj przenosi się między GitHub a GitLab bez większych uszkodzeń.

Integracje platformowe nie przenoszą się tak niezawodnie. Odwołania do zgłoszeń, wspomnienia użytkowników, diagramy, obsługa matematyki i specjalna składnia bloków mogą zachowywać się inaczej, nawet gdy podstawowy Markdown pozostaje czytelny.

Macierz wsparcia platformowego

Ta macierz opisuje typowe zachowanie domyślne. Motywy, wtyczki, rozszerzenia i konfiguracja mogą zmieniać pojedyncze komórki.

„Tak” nadal nie gwarantuje identycznego HTML ani wizualnej prezentacji. Oznacza to, że środowisko rozpoznaje ogólną funkcję.

Składnia, która jest zwykle bezpieczna wszędzie

Najbezpieczniejszy przenośny podzbiór obejmuje:

• Nagłówki ATX używające #
• Zwykłe akapity
• Puste linie między blokami
• - dla list nieuporządkowanych
• 1. dla list uporządkowanych
• Bloki kodu z ogranicznikami używające backticks
• Kod inline używający backticks
• Wyróżnienie używające *text*
• Mocne wyróżnienie używające **text**
• Zwykłe linki
• Zwykłe obrazy
• Cytaty blokowe
• Linie tematyczne (separatora)
• Jawne automatyczne linki w nawiasach kwadratowych

Celowo konserwatywny dokument mógłby wyglądać tak:

# Deployment Guide

This guide explains how to deploy the service.

## Requirements

- Docker
- Linux
- A supported GPU

## Configuration

Create a file named `compose.yaml`.

```yaml
services:
  application:
    image: example/application:1.0
```

For more information, see the [configuration reference](config.md).

> Back up existing data before upgrading.

Ta składnia dobrze się przenosi, ponieważ nie zależy od tabel, przypisów dolnych, atrybutów, calloutów ani przetwarzania platformowego.

Składnia, która często się psuje

Problemy z przenośnością mają tendencję do skupiania się wokół małej liczby funkcji.

Tabele z użyciem pipe

Tabele z użyciem pipe są dobrze wspierane przez narzędzia orientowane na GFM, ale nie przez ściśle CommonMark.

Tabela może degradować się w nieczytelny tekst, gdy zostanie przetransportowana przez parser, który jej nie rozpoznaje. Dla bardzo przenośnych dokumentów, rozważ krótkie listy lub semantyczny HTML generowany podczas etapu budowania.

Przypisy dolne

Składnia przypisów dolnych stała się powszechna, ale nadal jest to rozszerzenie.

Różne narzędzia mogą:

• Wspierać tylko jeden format przypisów
• Umieszczać przypisy w różnych miejscach
• Generować różne identyfikatory
• Odrzucać przypisy z wielu akapitów
• Renderować źródło dosłownie

Używaj przypisów dolnych, gdy znany jest potok wydawniczy. Unikaj polegania na nich w plikach README, które muszą się renderować na dowolnych systemach.

ID i atrybuty nagłówków

Ta składnia Pandoc nie jest przenośna:

## Installation {#installation .procedure}

Używaj zwykłego nagłówka i pozwól rendererowi wygenerować własną kotwicę, gdy przenośność ma znaczenie.

Unikaj również twardego kodowania linków do automatycznie generowanych ID nagłówków, chyba że każdy cel używa tych samych zasad slugifikacji.

Callouts i alerty

GitHub, Obsidian, GitLab, MkDocs, Docusaurus i motywy Hugo mogą wspierać bloki podobne do calloutów, ale często używają różnych składni.

Przenośnym fallbackiem jest zwykły cytat blokowy:

> Warning: Back up the database before upgrading.

Jest on mniej wizualnie imponujący, ale zachowuje znaczenie wszędzie.

Linki Wiki

Linki Wiki są zwięzłe wewnątrz narzędzi do zarządzania wiedzą:

[[KV Cache]]

Są to słaba składnia wymiany, ponieważ ścieżka docelowa, nazwa pliku, zasady nagłówków i zachowanie rozszerzania należą do aplikacji.

Używaj standardowych linków Markdown w treści przeznaczonej do publikacji:

[KV cache](kv-cache.md)

Surowy HTML

Surowy HTML to zwykły hak awaryjny, gdy Markdown nie może wyrazić układu. Jest to również częsta awaria przenośności i bezpieczeństwa.

Renderer może:

• Usunąć HTML
• Uciec przed nim (escape)
• Oczyszczać wybrane elementy
• Zezwalać na bloki, ale nie na elementy inline
• Odmawiać parsowania Markdown wewnątrz HTML
• Przypuszczać go bez zmian tylko w trybie zaufanym

Używaj surowego HTML tylko wtedy, gdy docelowy cel publikacji jest kontrolowany.

Notacja matematyczna

Matematyka ograniczona dolarami jest popularna, ale nie jest uniwersalnie interpretowana.

Źródło:

The complexity is $O(n^2)$.

może stać się:

• Zrenderowaną matematyką
• Zwykłym tekstem z znakami dolarów
• Nieprawidłowym wyróżnieniem
• Wejściem do innego parsera matematycznego

Wybierz jeden potok matematyczny i przetestuj go w każdym docelowym środowisku.

Mermaid i inne bloki diagramów

Ogranicznik kodu Mermaid jest syntaktycznie bezpieczny, ponieważ niespierane renderery zwykle wyświetlają go jako kod.

Wynik semantyczny jest nadal inny. Czytelnicy mogą zobaczyć zrenderowany diagram architektury w GitHub i surowe źródło Mermaid w innym środowisku.

To jest grzeczna degradacja, a nie prawdziwa kompatybilność.

Trzy warstwy kompatybilności Markdown

Pomaga rozdzielić kompatybilność na trzy warstwy.

Warstwa 1: Kompatybilność parsowania

Czy parser rozpoznaje strukturę?

Przykłady obejmują nagłówki, tabele, przypisy dolne i podzielone bloki.

Warstwa 2: Kompatybilność transformacji

Czy platforma stosuje dodatkowe przetwarzanie?

Przykłady obejmują:

• Renderowanie Mermaid
• Rozwiązywanie cytowań
• Rozszerzanie linków Wiki
• Łączenie numerów zgłoszeń
• Przetwarzanie shortcode
• Generowanie spisu treści

Warstwa 3: Kompatybilność prezentacji

Czy wynik wygląda i zachowuje się odpowiednio?

Przykłady obejmują:

• Stylowanie tabel
• Podświetlanie składni
• Kolory alertów
• Kotwice nagłówków
• Responsywne obrazy
• Umiejscowienie przypisów dolnych
• Czcionki matematyczne

Dwie platformy mogą parsować identyczną składnię, tworząc zasadniczo różną prezentację.

Lepszy model przenośności

Zamiast pytać, czy plik jest „poprawnym Markdown”, zadaj cztery węższe pytania:

1. W jakim dialekcie napisane jest źródło?
2. Który parser je czyta?
3. Jakie rozszerzenia są włączone?
4. Jakie transformacje platformy wykonują się następnie?

Na przykład:

Dialect: CommonMark plus GFM tables
Parser: Goldmark
Extensions: tables, strikethrough, task lists, footnotes
Platform: Hugo
Additional processing: render hooks and Mermaid JavaScript

Ten opis jest znacznie bardziej użyteczny niż mówienie, że „strona używa Markdown”.

Wybór dialektu według przypadku użycia

Pliki README

Używaj GFM.

Pliki README korzystają z:

• Tabel
• List zadań
• Kodu z ogranicznikami
• Automatycznych linków
• Przekreślenia
• Odwołań GitHub

Unikaj nadmiernego polegania na funkcjach tylko GitHuba, gdy repozytorium jest lustrzane na GitLab, renderowane w rejestrze pakietów lub włączone w generowaną dokumentację.

Artykuły techniczne w Hugo

Używaj Markdown zgodnego z CommonMark z udokumentowanym zestawem rozszerzeń Goldmark.

Tabele, kody z ogranicznikami, przypisy dolne i Mermaid mogą być rozsądne, ponieważ kontrolujesz potok budowania. Preferuj shortcode Hugo lub hook renderowania nad osadzaniem dużych ilości surowego HTML.

Utrzymuj składnię specyficzną dla Hugo zizolowaną i łatwo znajdowalną.

Dokumenty akademickie

Używaj Pandoc Markdown.

Cytowania, przetwarzanie bibliografii, przypisy dolne, metadane, notacja matematyczna, odwołania krzyżowe i konwersja do PDF lub DOCX uzasadniają zredukowaną przenośność.

Przechowuj polecenie Pandoc, plik domyślnych ustawień, filtry, bibliografię i szablony obok źródła. Sam plik źródłowy nie w pełni opisuje budowania.

Książki i dokumentacja długiego formatu

Pandoc Markdown jest zazwyczaj najsilniejszą z trzech opcji, gdy wiele formatów wyjściowych ma znaczenie.

Listy definicyjne, cytowania, atrybuty, metadane i strukturalne transformacje stają się ważniejsze, gdy złożoność dokumentu rośnie.

Dla dokumentacji tylko internetowej hostowanej w repozytorium Git, GFM lub generator dokumentacji oparty na CommonMark może pozostać prostszy.

Notatki i osobiste bazy wiedzy

Używaj natywnej składni wybranej aplikacji do notatek, gdy funkcje aplikacji zapewniają realną wartość.

Linki Wiki, osadzenia i callouts Obsidian są użyteczne wewnątrz skarbca. Traktuj eksport jako proces kompilacji, a nie zakładaj, że surowe pliki są już przenośnymi publikacjami.

Wspólna dokumentacja w nieznanym systemach

Używaj konserwatywnego podzbioru CommonMark.

Unikaj:

• Linków Wiki
• Alertów platformowych
• Atrybutów nagłówków
• Cytowań
• Surowego HTML
• Niestandardowych kontenerów
• Osadzeń aplikacji
• Shortcode

Przenośność zazwyczaj wymaga rezygnacji z funkcji wygodnych.

Praktyczne zasady dla przenośnego Markdown

Zacznij od struktury CommonMark

Używaj CommonMark dla szkieletu dokumentu:

• Nagłówki
• Akapity
• Listy
• Linki
• Obrazy
• Cytaty blokowe
• Bloki kodu

Zapewnia to, że główne znaczenie przetrwa nawet, gdy opcjonalne rozszerzenia zawiodą.

Dodawaj funkcje GFM świadomie

Tabele i listy zadań są rozsądne, gdy wszystkie ważne cele je wspierają.

Nie zakładaj, że „większość narzędzi wspiera GFM” bez testowania dokładnego celu. Niektóre twierdzą zgodność z GFM, włączając tylko wybrane rozszerzenia.

Izoluj rozszerzenia platformowe

Utrzymuj składnię specyficzną dla platformy w wyraźnie identyfikowalnych blokach.

Na przykład, scentralizuj shortcode Hugo, cytowania Pandoc lub osadzenia Obsidian, zamiast rozrzucać je przez każdy akapit.

Izolacja ułatwia późniejszą konwersję.

Preferuj grzeczną degradację

Blok Mermaid degraduje się w czytelny kod źródłowy. Alert GitHub degradował się w cytat blokowy.

Osadzenie Wiki może degradować się w niejasną nazwę pliku, a podzielony blok Pandoc może ujawnić interpunkcję wokół treści.

Wybieraj rozszerzenia, których fallback pozostaje zrozumiały.

Nie polegaj na automatycznie generowanych ID nagłówków

Algorytmy kotwic nagłówków różnią się między GitHub, Hugo, Pandoc i generatorami dokumentacji.

Dla linków między dokumentami, używaj jawnych ID wspieranych przez renderera tylko wtedy, gdy docelowy potok jest kontrolowany. W przeciwnym razie linkuj do dokumentu, a nie do wygenerowanego fragmentu.

Przechowuj konfigurację budowania z treścią

Rozszerzenia Pandoc, ustawienia Hugo, wtyczki, filtry i integracje JavaScript określają, jak Markdown się zachowuje.

Committyj powiązane pliki konfiguracyjne ze źródłem:

content/
  article.md
pandoc.yaml
references.bib
config/
  _default/
    markup.yaml
layouts/
  _default/
    _markup/

Samo rozszerzenie .md nie przechwytuje środowiska wydawniczego. Dla strukturalnego podejścia do dokumentowania tych decyzji, zobacz Rekordy decyzyjne w rozwoju napędzanym przez AI.

Testuj Markdown przeciwko każdemu ważnemu celowi

Wizualny podgląd w jednym edytorze to za mało. Edytor może wspierać bogatszy dialekt niż renderer produkcyjny.

Dla Pandoc, testuj jawne formaty wejściowe:

pandoc --from=commonmark article.md -o commonmark.html
pandoc --from=gfm article.md -o gfm.html
pandoc --from=markdown article.md -o pandoc.html

Ostrzeżenia i widoczna interpunkcja źródłowa ujawniają, które funkcje są specyficzne dla dialektu.

Dla Hugo, zbuduj stronę produkcyjną:

hugo --gc --minify

Następnie sprawdzaj wygenerowany HTML, zamiast polegać tylko na podglądzie w edytorze.

Dla repozytoriów, wyświetlaj commitowany plik na faktycznej platformie hostingowej. Lokalne rozszerzenia Markdown w VS Code mogą nie pasować do GitHub lub GitLab.

Rozwiązywanie typowych niezgodności renderowania

Gdy plik, który działał na jednej platformie, psuje się na innej, awaria zwykle należy do jednej z kilku powtarzalnych wzorców. Tabela poniżej wymienia symptom tak, jakbyś go faktycznie widział, najbardziej prawdopodobną przyczynę oraz konkretne polecenie lub sprawdzenie do potwierdzenia i naprawy.

To jest najszybsza pierwsza analiza przed zakładaniem „błędu” Markdown — większość tych niezgodności to brakujące rozszerzenie lub funkcja tylko platformowa, a nie zepsuta składnia. Dla problemów specyficznych dla bloków kodu, takich jak brakujące podświetlanie składni lub niespierane identyfikatory języka, zobacz dedykowany przewodnik o blokach kodu Markdown.

Lintuj przenośny podzbiór

Linter Markdown nie może gwarantować kompatybilności renderera, ale może usunąć unikane niejednoznaczności.

Użyteczne zasady obejmują:

• Używaj spójnych stylów nagłówków
• Dodawaj puste linie wokół list i bloków kodu
• Używaj kodu z ogranicznikami zamiast wciętym
• Określaj języki ograniczników kodu
• Unikaj pomijanych poziomów nagłówków
• Używaj spójnych znaczników list
• Unikaj niejednoznacznego wyróżnienia wokół interpunkcji
• Utrzymuj spójne zakończenia linii
• Waliduj linki i obrazy

Dla publikacji wielocelowej, dodaj test budowania dla każdego ważnego renderera, zamiast polegać tylko na lintingu składni.

Konwersja między dialektami za pomocą Pandoc

Pandoc może normalizować dokumenty z jednego dialektu na inny:

pandoc \
  --from=markdown \
  --to=gfm \
  article.md \
  -o article-gfm.md

Albo konwertować GFM na Pandoc Markdown:

pandoc \
  --from=gfm \
  --to=markdown \
  README.md \
  -o document.md

To jest użyteczne, ale konwersja nie jest gwarantowana do zachowania każdej funkcji.

Potencjalne straty obejmują:

• Odwołania specyficzne dla platformy
• Stylowanie calloutów
• Złożone tabele
• Osadzone obiekty aplikacji
• Niestandardowe atrybuty
• Zachowanie surowego HTML
• Składnia wtyczek
• Renderowanie diagramów
• Dokładne spacje i formatowanie

Pandoc zachowuje strukturę dokumentu lepiej niż oryginalne formatowanie źródła. Traktuj konwersję jako etap budowania, a nie odwracalny formatownik tekstu.

Rekomendowana strategia dla stron Hugo

Dla technicznego bloga Hugo, najpraktyczniejsza polityka to:

1. Używaj CommonMark dla rdzenia prozy i struktury.
2. Włącz mały udokumentowany zestaw rozszerzeń Goldmark.
3. Używaj tabel i list zadań w stylu GFM, gdzie poprawiają czytelność.
4. Implementuj Mermaid przez jeden spójny hook renderowania lub shortcode.
5. Obsługuj matematykę przez jeden udokumentowany potok KaTeX lub MathJax.
6. Używaj front matter Hugo tylko na początku plików treści.
7. Preferuj hook renderowania i shortcode nad surowym HTML.
8. Utrzymuj linki źródłowe jako standardowe linki Markdown, gdzie to możliwe.
9. Testuj migrowane lub zewnętrzne źródła dokumentów przez Hugo.
10. Dokumentuj każdą składnię, która nie renderuje się poprawnie w GitHub.

To podejście akceptuje, że treść Hugo nie jest uniwersalnie przenośna, zachowując przy tym widoczną granicę przenośności.

Najgorszym podejściem jest przypadkowe mieszanie dialektów: alerty GitHub, osadzenia Obsidian, atrybuty Pandoc i shortcode Hugo umieszczone w tym samym dokumencie bez zdefiniowanego potoku budowania.

Tabela decyzyjna

Wniosek

CommonMark, GitHub Flavored Markdown i Pandoc Markdown to nie konkurujące wersje tego samego produktu. Rozwiązują różne problemy.

CommonMark zapewnia niezawodną podstawę parsowania. GFM dodaje praktyczne funkcje do współpracy w oprogramowaniu, a Pandoc Markdown zmienia Markdown w bogaty język źródłowy do wydawania i konwersji.

Najbezpieczniejsza zasada jest prosta: pisz w najmniejszym dialekcie, który spełnia rzeczywisty cel. Używaj CommonMark, gdy treść musi podróżować, GFM, gdy kolaboracja w stylu GitHub jest celem, a Pandoc Markdown, gdy struktura dokumentu i formaty wyjściowe są ważniejsze niż uniwersalne renderowanie.

Przenośność Markdown nie jest osiągnięta przez unikanie każdego rozszerzenia. Jest osiągnięta przez wiedzę, które rozszerzenia są częścią kontraktu źródłowego i testowanie ich w każdym renderze, który ma znaczenie.

Referencje

• Specyfikacja CommonMark
• Specyfikacja GitHub Flavored Markdown
• Pandoc Markdown
• Dokumentacja Goldmark
• Konfiguracja Goldmark w Hugo
• Pisanie wyrażań matematycznych w GitHub