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

Markdown wygląda jak jeden język, dopóki ten sam plik nie wyświetli się inaczej na GitHubie, Hugo, Obsidianie lub Pandoc. Problemem nie jest to, że Markdown jest niepowiarygodny.

Problemem jest to, że „Markdown” opisuje rodzinę powiązanych składni, parserów i funkcji platformowych, a nie jeden uniwersalny format dokumentów. CommonMark definiuje precyzyjne, przenośne jądro, GitHub Flavored Markdown dodaje funkcje przydatne do współpracy nad oprogramowaniem, a Pandoc Markdown rozszerza język do formatu poważnego autorstwa dokumentów.

Wybór między nimi zależy od tego, gdzie dokument musi się renderować. Plik README, wpis na blogu Hugo i praca naukowa mają każde inne wymagania. To porównanie jest częścią szerszego obrazu narzędzi do dokumentacji i obejmuje formalne dialekty, rozszerzenia specyficzne dla platformy oraz praktyczne zasady przenośności, abyś mógł wybrać odpowiednią składnię dla swojego środowiska docelowego. Dla szybkiego odniesienia składniowego, szkolenie z Markdownu omawia podstawowe elementy formatowania.

Markdown to nie jeden język

Oryginalna składnia Markdown była celowo mała i luźno określona. Sprawiało to, że była łatwa do czytania i implementacji, ale różne parsery zaczęły interpretować niejednoznaczne dane wejściowe w różny sposób.

CommonMark został stworzony, aby zdefiniować spójne reguły parsowania dla podstawowych struktur Markdown. GitHub Flavored Markdown, zwykle nazywany GFM, buduje na tej podstawie kilka szeroko używanych rozszerzeń.

Pandoc Markdown podejmuje inne podejście. Zamiast pozostawać małą składnią zorientowaną na web, dodaje funkcje dokumentowe, takie jak cytaty, metadane, przypisy dolne, listy definicji, atrybuty i notacja matematyczna.

Uproszczona relacja wygląda następująco:

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

Krótka odpowiedź

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

Używaj GFM przy pisaniu plików README, pull requestów, szablonów problemów i dokumentacji technicznej przeznaczonej głównie dla platform zgodnych z GitHub.

Używaj Pandoc Markdown, gdy dokument źródłowy musi stać się PDF, DOCX, EPUB, LaTeX, slajdami lub pracą akademicką z cytatami i metadanymi.

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

Subiektywna opinia: jeśli zapamiętasz tylko jedną regułę dla technicznego bloga Hugo, traktuj CommonMark plus tabele i listy zadań w stylu GFM jako domyślne, a wszystko inne — przypisy dolne, matematykę, ostrzeżenia, atrybuty nagłówków — traktuj jako jawne, przetestowane rozszerzenie, a nie domyślne ustawienie. Ta jedna nawyka zapobiega większości awarii przenośności opisanych poniżej.

CommonMark: Przenośne jądro

CommonMark jest formalną specyfikacją podstawowego języka Markdown. Jego głównym wkładem nie jest duża kolekcja funkcji, ale spójne parsowanie.

Definiuje, jak parsery powinny interpretować:

• Akapity
• Nagłówki ATX i Setext
• Cytaty blokowe
• Listy uporządkowane i nieuporządkowane
• Zablokowane i wcięte bloki kodu
• Wyróżnienie i silne wyróżnienie
• Linki i obrazy
• Linki w stylu referencyjnym
• Kod w linii
• Przerwy tematyczne
• Surowe bloki HTML
• Twarde i miękkie łamanie linii

Dokument CommonMark może nadal zachowywać się inaczej na warstwie prezentacji. CSS, podświetlanie składni, kotwice nagłówków, sanitizacja HTML i polityki linków są poza podstawowymi regułami parsowania.

CommonMark należy więc traktować jako niezawodną podstawę strukturalną, a nie obietnicę, że każdy renderer wygeneruje identyczną stronę.

Przenośny przykład CommonMark

# Wdrożenie usługi

Usługa wystawia małe API HTTP.

## Wymagania

- Linux
- Docker
- 8 GB pamięci

## Uruchom usługę

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

Szczegóły znajdziesz w [przewodniku konfiguracji](configuration.md).

Ten rodzaj dokumentu działa w prawie każdym nowoczesnym środowisku Markdown. Używa nagłówków, akapitów, list, zablokowanego kodu i zwykłych linków, nie polegając na rozszerzeniach specyficznych dla dialektu.

GitHub Flavored Markdown: CommonMark dla projektów oprogramowania

GitHub Flavored Markdown to formalny dialekt oparty na CommonMark. Zachowuje model parsowania CommonMark i dodaje funkcje często potrzebne w dokumentacji repozytorium i współpracy.

Formalna specyfikacja GFM dodaje:

• Tabele z potkami
• Elementy list zadań
• Przekreślenie
• Rozszerzone autolinki
• Ograniczenia wokół niektórych surowych tagów HTML

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

Tabele GFM

| Backend | Najlepsze zastosowanie |
|---|---|
| Ollama | Lokalne eksperymenty |
| vLLM | Współdzielona inferencja |
| SGLang | Ustrukturyzowane obciążenia |

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

Listy zadań GFM

- [x] Zainstaluj Docker
- [x] Pobierz model
- [ ] Dodaj monitoring

Składnia list zadań jest przydatna w problemach, pull requestach i dokumentacji projektów. Poza wspierającym rendererem może wyglądać jak zwykła lista zawierająca dosłowne nawiasy kwadratowe.

Przekreślenie GFM

Użyj ~~starego endpointu~~ nowego endpointu.

Przekreślenie jest szeroko wspierane, ale nadal jest rozszerzeniem, a nie przenośną składnią CommonMark.

Autolinki GFM

GFM rozpoznaje więcej tekstu przypominającego URL i adresy e-mail bez wymagania nawiasów kątowych lub jawnej składni linków.

Odwiedź https://example.com/docs po szczegóły.

W ścisłym CommonMark jawne autolinki używają nawiasów kątowych:

<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ęłym źródłem nieporozumień jest założenie, że każda funkcja Markdown widoczna na GitHub należy do specyfikacji GFM.

Nie jest to prawdą.

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

• Wyrażenia matematyczne
• Diagramy Mermaid
• Alerty
• Referencje do problemów i pull requestów
• Wzmianki o użytkownikach i zespołach
• Referencje do commitów
• Skróty emoji
• Składane sekcje HTML
• Podgląd kolorów
• Linki względne do repozytorium
• Automatyczne kotwice nagłówków

Niektóre z tych funkcji to rozszerzenia składniowe. Inne to zachowanie post-procesujące lub integracje z danymi GitHub.

Ta różnica ma znaczenie, ponieważ inny renderer może zgodnie z prawdą twierdzić o zgodności z GFM, nie implementując renderera matematycznego GitHuba, integracji z Mermaid, referencji do problemów lub stylizacji alertów.

Diagramy Mermaid na GitHubie

GitHub renderuje zablokowany blok kodu oznaczony jako mermaid jako diagram:

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

Ogólny renderer GFM może wyświetlić ten sam blok jako podświetlony kod źródłowy. Markdown pozostaje ważny, ale ulepszona prezentacja jest specyficzna dla platformy. Aby uzyskać praktyczne wprowadzenie do składni Mermaid, zobacz Szybki start z diagramami Mermaid.

Wyrażenia matematyczne na GitHubie

GitHub wspiera wyrażenia matematyczne w linii i blokowe, używając delimitatorów dolarowych i dodatkowych form ucieczki.

Rozmiar pamięci podręcznej wynosi około $2nlhd$ bajtów.

$$
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 matematyczne Pandoc.

Alerty GitHub

GitHub wspiera cytaty blokowe w stylu alertów, takie jak:

> [!WARNING]
> Zmiana tego ustawienia czyści pamięć podręczną.

Na GitHub może to wyglądać jako stylizowane ostrzeżenie. Na zwykłym rendererze CommonMark zwykle pojawia się jako zwykły cytat blokowy zawierający [!WARNING].

Ten fallback jest czytelny, co sprawia, że alerty GitHub są mniej niebezpieczne niż rozszerzenia, które całkowicie znikają. Nadal nie są one przenośnymi elementami prezentacji.

Pandoc Markdown: Markdown jako język dokumentów

Pandoc Markdown jest zaprojektowany do konwersji dokumentów, a nie 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.

Domyślny czytnik Markdown zawiera duży zestaw rozszerzeń. Ważne możliwości obejmują:

• Bloki metadanych YAML
• Przypisy dolne
• Cyty
• Wiele formatów tabel
• Listy definicji
• Notacja matematyczna
• Identyfikatory i atrybuty nagłówków
• Atrybuty bloków kodu
• Zablokowane dywizje
• Spany w nawiasach
• Indeksy górne i dolne
• Przekreślenie
• Bloki linii
• Numerowane listy przykładów
• Surowy LaTeX
• Surowy HTML
• Automatyczne numerowanie sekcji
• Przetwarzanie bibliografii

Pandoc Markdown jest znacznie bardziej ekspresywny niż CommonMark lub formalny GFM. Ta ekspresywność sprawia, że jest potężny do publikacji, ale mniej bezpieczny jako format wymiany.

Przypisy dolne Pandoc

Markdown ma kilka nieskompatybilnych dialektów.[^dialects]

[^dialects]: CommonMark, GFM i Pandoc Markdown to trzy
    ważne przykłady.

Składnia przypisów dolnych jest wspierana przez wiele nowoczesnych narzędzi, ale nie jest częścią CommonMark lub 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 zgodność tylko z CommonMark lub GFM może ich nie wspierać.

Cyty Pandoc

PagedAttention ulepsza zarządzanie pamięcią KV cache
[@kwon2023pagedattention].

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

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

Składnia cytowań pozostaje czytelna w niewspieranym rendererze, ale nie stanie się sformatowanym odniesieniem bez Pandoc lub innego kompatybilnego procesora cytowań. Elastyczność strony czytnika Pandoc leży również u podstaw przepływów pracy konwersji w przeciwnym kierunku — zobacz konwersję dokumentów Word do Markdown jako praktyczny przykład użycia rozszerzonego dialektu Pandoc jako formatu pośredniego.

Listy definicji Pandoc

CommonMark
: Precyzyjna specyfikacja dla jądra Markdown.

GFM
: Dialekt oparty na CommonMark z rozszerzeniami zorientowanymi na oprogramowanie.

Pandoc Markdown
: Rozszerzony format autorstwa do konwersji dokumentów.

Listy definicji są przydatne w podręcznikach, glosariach i książkach technicznych. Normalnie słabo się degradują w rendererach, które ich nie obsługują, ponieważ linie z dwukropkiem pozostają widoczne jako zwykły tekst.

Atrybuty nagłówków Pandoc

## Konfiguracja pamięci podręcznej {#cache-config .deployment}

Pandoc interpretuje nawiasy klamrowe jako jawny identyfikator i listę klas. Wiele innych rendererów Markdown wyświetla tekst atrybutu bezpośrednio w nagłówku.

Jest to jeden z najjasniejszych przykładów przydatnej składni, której nie należy umieszczać w dokumencie, którego oczekuje się renderowania wszędzie.

Zablokowane dywizje Pandoc

::: warning
Zmiana tej opcji restartuje serwer.

Pandoc konwertuje to na dywizję strukturalną z klasą. Szablony, CSS, filtry lub pisarze wyjściowe mogą zdecydować, jak ta struktura powinna wyglądać.

Większość rendererów CommonMark i GFM nie rozpoznaje zablokowania. Wyświetlają dwukropki i treść 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.

Która składnia działa na GitHubie?

Dla plików README, problemów, pull requestów, dyskusji i wiki, GFM jest naturalną podstawą.

Ogólnie możesz używać:

• Składni CommonMark
• Tabel
• List zadań
• Przekreślenia
• Rozszerzonych autolinków
• Zablokowań kodu z podświetlaniem składni
• Referencji specyficznych dla GitHub
• Matematyki wspieranej przez GitHub
• Diagramów wspieranych przez GitHub
• Alertów GitHub
• Przypisów dolnych tam, gdzie są wspierane przez powierzchnię treści

Ryzyko przenośności zaczyna się, gdy GitHub wykonuje dodatkowe renderowanie poza formalnym GFM. Diagramy Mermaid, notacja matematyczna, referencje do problemów i prezentacja alertów mogą nie przetrwać poza GitHub.

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

Która składnia działa w Hugo?

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

W typowej konfiguracji Hugo dobrze działają:

• Struktura CommonMark
• Zablokowane bloki kodu
• Tabele z potkami
• Przekreślenie
• Listy zadań
• Automatyczne ID nagłówków
• Podświetlanie składni
• Przypisy dolne, gdy rozszerzenie jest włączone
• Listy definicji, gdy są włączone
• Podstawienia typograficzne, gdy są włączone

Hugo dodaje również funkcje poza Markdown przez:

• Front matter
• Skróty (Shortcodes)
• Render hooks
• Zasoby stron
• Funkcje referencyjne wewnętrzne
• Przetwarzanie szablonów
• Konfigurację strony

Te funkcje Hugo nie podróżują z plikiem Markdown. Aby uzyskać praktyczny przykład wdrożenia Hugo, zobacz Wdrożenie Hugo do AWS S3.

Front Matter Hugo nie jest treścią Markdown

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

---
title: "Kompatybilność Markdown"
description: "Porównaj dialekty Markdown i renderery."
date: 2026-07-31
tags:
  - Markdown
  - dokumentacja
---

Pandoc może również rozpoznawać bloki metadanych YAML, ale interpretuje pola zgodnie ze swoimi szablonami i pisarzami. GitHub normalnie 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 być więc rozpoznana w więcej niż jednym narzędziu, nie mając tego samego znaczenia.

Surowy HTML w Hugo

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

Blok taki jak:

<div class="notice">
  Restartuj usługę po zmianie tej wartości.
</div>

może zostać pominięty, chyba że renderowanie surowego HTML jest włączone lub treść jest zaimplementowana przez shortcode lub render hook.

Dla kontrolowanego bloga technicznego włączanie surowego HTML może być rozsądne. Nadal sprawia, że źródło jest mniej przenośne i powinno być świadomą decyzją na poziomie strony.

Mermaid w Hugo

Zablokowany blok mermaid jest nadal tylko blokiem kodu, dopóki tema Hugo, render hook, 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.

Która składnia działa w Pandoc?

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

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

Jest to jedna z najbardziej przydatnych funkcji przenośności Pandoc. Operator może powiedzieć Pandoc, który dialekt źródło twierdzi, że używa, zamiast polegać na niejasnym rozszerzeniu pliku .md.

Pandoc pozwala również włączyć lub wyłączyć 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żesz 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, że „Pandoc Markdown” nie jest zawsze jedną stałą konfiguracją. Komendy build i pliki domyślne są częścią specyfikacji dokumentu.

Która składnia działa w Obsidian?

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

Typowe przykłady obejmują:

• Linki Wiki
• Osadzone notatki
• Osadzone pliki
• Callouty
• Referencje do bloków
• Tagi
• Właściwości
• Podświetlanie
• Komentarze
• Zapytania Dataview z wtyczek
• Linki URI specyficzne dla aplikacji

Link Wiki taki jak:

[[Kompatybilność Markdown]]

jest znaczący wewnątrz skarbca Obsidian. GitHub, CommonMark i domyślny czytnik Pandoc normalnie wyświetlają go jako dosłowny tekst w nawiasach.

Osadzenie jest jeszcze bardziej specyficzne dla aplikacji:

![[compatibility-table]]

Referencjonowana treść nie jest obecna w samym pliku. Eksportowanie lub publikowanie notatki wymaga więc kroku ekspansji, który rozwiązuje osadzenie.

Obsidian jest dobrym przykładem tego, dlaczego przechowywanie w plikach .md nie gwarantuje przenośności Markdown. Aby uzyskać praktyczne spojrzenie na Obsidian jako narzędzie do zarządzania wiedzą, zobacz Obsidian do osobistego zarządzania wiedzą.

Która składnia działa w GitLab?

GitLab Flavored Markdown używa CommonMark jako jądra i obejmuje funkcje GFM, takie jak tabele i listy zadań. Następnie dodaje zachowanie specyficzne dla GitLab, w tym przekrzyżowane referencje, notację matematyczną, diagramy i inne funkcje współpracy.

README napisany w konserwatywnym GFM zazwyczaj przenosi się między GitHub a GitLab bez poważnych uszkodzeń.

Integracje platformowe nie podróżują tak niezawodnie. Referencje do problemów, wzmianki o użytkownikach, diagramy, przetwarzanie matematyki i specjalna składnia bloków mogą zachowywać się inaczej, nawet gdy podstawowy Markdown pozostaje czytelny.

Macierza wsparcia platform

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

„Tak” nadal nie gwarantuje identycznego HTML lub 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
• Zablokowane bloki kodu używające apostrofów
• Kod w linii używający apostrofów
• Wyróżnienie używające *text*
• Silne wyróżnienie używające **text**
• Zwykłe linki
• Zwykłe obrazy
• Cytaty blokowe
• Przerwy tematyczne
• Jawne autolinki w nawiasach kątowych

Celowo konserwatywny dokument może wyglądać tak:

# Przewodnik wdrożeniowy

Ten przewodnik wyjaśnia, jak wdrożyć usługę.

## Wymagania

- Docker
- Linux
- Wspierany GPU

## Konfiguracja

Stwórz plik o nazwie `compose.yaml`.

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

Więcej informacji znajdziesz w [referencji konfiguracji](config.md).

> Zrób kopię istniejących danych przed aktualizacją.

Ta składnia dobrze podróżuje, ponieważ nie zależy od tabel, przypisów dolnych, atrybutów, calloutów lub przetwarzania platformy.

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 potkami

Tabele z potkami są dobrze wspierane przez narzędzia zorientowane na GFM, ale nie przez ścisły CommonMark.

Tabela może zdegenerować się w nieczytelny tekst, gdy przejdzie przez parser, który jej nie rozpoznaje. Dla highly portable documents, rozważ krótkie listy lub semantyczny HTML generowany podczas kroku build.

Przypisy dolne

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

Różne narzędzia mogą:

• Wspierać tylko jeden format przypisów dolnych
• Umieszczać przypisy dolne inaczej
• Generować różne identyfikatory
• Odrzucać przypisy dolne wieloakapitowe
• Renderować źródło dosłownie

Używaj przypisów dolnych, gdy przepływ publikacji jest znany. Unikaj polegania na nich w plikach README, które muszą renderować się przez dowolne systemy.

ID nagłówków i atrybuty

Ta składnia Pandoc nie jest przenośna:

## Instalacja {#installation .procedure}

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

Unikaj również hard-codingu linków do auto-generowanych ID nagłówków, chyba że każdy cel używa tych samych reguł slugifikacji.

Callouty i alerty

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

Przenośny fallback to zwykły cytat blokowy:

> Ostrzeżenie: Zrób kopię bazy danych przed aktualizacją.

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

Linki Wiki

Linki Wiki są zwięzłe w narzędziach do zarządzania wiedzą:

[[KV Cache]]

Są słabą składnią wymiany, ponieważ ścieżka celu, nazwa pliku, reguły nagłówków i zachowanie rozwiązywania 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 typowa luka bezpieczeństwa, 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 go
• Sanitaryzować wybrane elementy
• Pozwolić na bloki, ale nie elementy w linii
• Odrzucać parsowanie Markdown wewnątrz HTML
• Przekazywać go bez zmian tylko w trybie zaufanym

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

Notacja matematyczna

Matematyka z delimitatorami dolarowymi jest popularna, ale nie uniwersalnie interpretowana.

Źródło:

Złożoność wynosi $O(n^2)$.

może stać się:

• Wyrenderowaną matematyką
• Zwykłym tekstem ze znakami dolarowymi
• Nieprawidłowym wyróżnieniem
• Dane wejściowe do innego parsera matematycznego

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

Mermaid i inne bloki diagramów

Zablokowanie kodu Mermaid jest składniowo bezpieczne, ponieważ niewspierane renderery normalnie wyświetlają je jako kod.

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

Jest to graceful degradation, a nie prawdziwa kompatybilność.

Trzy warstwy kompatybilności Markdown

Pomaga oddzielić kompatybilność na trzy warstwy.

Warstwa 1: Kompatybilność parsowania

Czy parser rozpoznaje strukturę?

Przykłady obejmują nagłówki, tabele, przypisy dolne i zablokowane dywizje.

Warstwa 2: Kompatybilność transformacji

Czy platforma stosuje dodatkowe przetwarzanie?

Przykłady obejmują:

• Renderowanie Mermaid
• Rozwiązywanie cytowań
• Rozszerzanie linków wiki
• Łączenie numerów problemów
• Przetwarzanie skróty
• Generowanie spisu treści

Warstwa 3: Kompatybilność prezentacji

Czy wynik wygląda i zachowuje się odpowiednio?

Przykłady obejmują:

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

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

Lepszy model przenośności

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

1. W którym dialekcie jest napisane źródło?
2. Który parser go czyta?
3. Które rozszerzenia są włączone?
4. Które transformacje platformy uruchamiają się później?

Na przykład:

Dialekt: CommonMark plus tabele GFM
Parser: Goldmark
Rozszerzenia: tabele, przekreślenie, listy zadań, przypisy dolne
Platforma: Hugo
Dodatkowe przetwarzanie: render hooks i Mermaid JavaScript

To opisanie jest znacznie bardziej przydatne niż mówienie „strona używa Markdown”.

Wybór dialektu według przypadku użycia

Pliki README

Używaj GFM.

Pliki README korzystają z:

• Tabel
• List zadań
• Zablokowanego kodu
• Autolinków
• Przekreślenia
• Referencji GitHub

Unikaj nadmiernego polegania na funkcjach tylko GitHub, gdy repozytorium jest lustrzane do GitLab, renderowane na rejestrze pakietów lub zawarte w generowanej dokumentacji.

Artykuły techniczne Hugo

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

Tabele, zablokowania kodu, przypisy dolne i Mermaid mogą być rozsądne, ponieważ kontrolujesz potok build. Wol preferuj shortcodes Hugo lub render hooks przed osadzaniem dużych ilości surowego HTML.

Trzymaj składnię specyficzną dla Hugo izolowaną i łatwą do znalezienia.

Dokumenty akademickie

Używaj Pandoc Markdown.

Cytaty, przetwarzanie bibliografii, przypisy dolne, metadane, notacja matematyczna, przekrzyżowane referencje i konwersja do PDF lub DOCX uzasadniają zmniejszoną przenośność.

Przechowuj komendę Pandoc, plik domyślny, filtry, bibliografię i szablony obok źródła. Sam plik źródłowy nie opisuje w pełni buildu.

Książki i dokumentacja długiego formatu

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

Listy definicji, cytaty, atrybuty, metadane i ustrukturyzowane transformacje stają się ważniejsze wraz ze wzrostem złożoności dokumentu.

Dla dokumentacji tylko w sieci 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 notatek, gdy funkcje aplikacji dostarczają realnej wartości.

Linki wiki, osadzenia i callouty Obsidian są przydatne wewnątrz skarbca. Traktuj eksport jako proces kompilacji, zamiast zakładać, że surowe pliki są już przenośnymi publikacjami.

Współdzielona dokumentacja przez nieznane systemy

Używaj konserwatywnego podzbioru CommonMark.

Unikaj:

• Linków Wiki
• Alertów platformy
• Atrybutów nagłówków
• Cytowań
• Surowego HTML
• Niestandardowych kontenerów
• Osadzeń aplikacji
• Skróty

Przenośność zwykle wymaga rezygnacji z funkcji wygody.

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

To zapewnia, ż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 „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 platformy

Trzymaj składnię specyficzną dla platformy w wyraźnie rozpoznawalnych blokach.

Na przykład, centralizuj shortcodes Hugo, cytaty Pandoc lub osadzenia Obsidian, zamiast rozrzucać je przez każdy akapit.

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

Wol graceful degradation

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

Osadzenie wiki może zdegenerować się w niewytłumaczoną nazwę pliku, podczas gdy zablokowana dywizja Pandoc może odsłonić interpunkcję wokół treści.

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

Nie polegaj na auto-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-dokumentów, używaj jawnych ID wspieranych przez renderer tylko wtedy, gdy potok celu jest kontrolowany. W przeciwnym razie, linkuj do dokumentu, a nie do wygenerowanego fragmentu.

Przechowuj konfigurację build z treścią

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

Zakommituj odpowiednie pliki konfiguracyjne ze źródłem:

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

Rozszerzenie .md samo w sobie nie przechwytuje środowiska publikacyjnego. Aby uzyskać ustrukturyzowane podejście do dokumentowania tych decyzji, zobacz Rejestr decyzji dla rozwoju napędzanego przez AI.

Testuj Markdown przeciwko każdemu ważnemu celowi

Podgląd wizualny w jednym edytorze nie jest wystarczający. Edytor może wspierać bogatszy dialekt niż renderer produkcyjny.

Dla Pandoc, przetestuj 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 sprawdź wygenerowany HTML, zamiast polegać tylko na podglądzie edytora.

Dla repozytoriów, podglądaj zakomitowany plik na rzeczywistej platformie hostingowej. Lokalne rozszerzenia Markdown w VS Code mogą nie pasować do GitHub lub GitLab.

Rozwiązywanie problemów z powszechnymi rozbieżnościami renderowania

Gdy plik, który działał na jednej platformie, psuje się na innej, awaria zwykle wpada w jeden z kilku powtarzalnych wzorców. Poniższa tabela列出 symptom tak, jak go naprawdę zobaczysz, najbardziej prawdopodobną przyczynę i konkretną komendę lub sprawdzenie, aby potwierdzić i naprawić.

To najszybsze pierwsze przejście przed założeniem „błędu” Markdown — większość tych rozbieżności to brakujące rozszerzenie lub funkcja tylko platformy, a nie zepsuta składnia. Dla problemów specyficznych dla zablokowań kodu, takich jak brakujące podświetlanie składni lub niewspierane identyfikatory języków, zobacz dedykowany przewodnik na temat bloków kodu Markdown.

Lintuj przenośny podzbiór

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

Przydatne reguły obejmują:

• Używaj spójnych stylów nagłówków
• Dodawaj puste linie wokół list i bloków kodu
• Używaj zablokowanego zamiast wciętego kodu
• Określ języki zablokowań kodu
• Unikaj pomijanych poziomów nagłówków
• Używaj spójnych markerów list
• Unikaj niejednoznacznego wyróżnienia wokół interpunkcji
• Trzymaj zakończenia linii spójne
• Waliduj linki i obrazy

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

Konwersja między dialektami z Pandoc

Pandoc może normalizować dokumenty z jednego dialektu do innego:

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

Albo przekonwertuj GFM do Pandoc Markdown:

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

To jest przydatne, ale konwersja nie gwarantuje zachowania każdej funkcji.

Potencjalne straty obejmują:

• Referencje specyficzne dla platformy
• Stylizację calloutów
• Skomplikowane tabele
• Osadzone obiekty aplikacji
• Niestandardowe atrybuty
• Zachowanie surowego HTML
• Składnię wtyczek
• Renderowanie diagramów
• Dokładną białą spację i formatowanie

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

Rekomendowana strategia dla stron Hugo

Dla technicznego bloga Hugo, najbardziej praktyczną polityką jest:

1. Używaj CommonMark dla rdzeniowego prozy i struktury.
2. Włącz mały, udokumentowany zestaw rozszerzeń Goldmark.
3. Używaj tabel i list zadań w stylu GFM tam, gdzie poprawiają czytelność.
4. Implementuj Mermaid przez jeden spójny render hook 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. Wol preferuj render hooks i shortcodes przed surowym HTML.
8. Trzymaj linki źródłowe jako standardowe linki Markdown, gdzie to możliwe.
9. Testuj migrowane lub zewnętrznie źródłowe dokumenty przez Hugo.
10. Dokumentuj każdą składnię, która nie będzie renderować się poprawnie na GitHub.

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

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

Tabela decyzji

Wniosek

CommonMark, GitHub Flavored Markdown i Pandoc Markdown nie są konkurującymi wersjami tego samego produktu. Rozwiązują różne problemy.

CommonMark dostarcza niezawodną podstawę parsowania. GFM dodaje praktyczne funkcje dla współpracy nad oprogramowaniem, podczas gdy Pandoc Markdown przekształca Markdown w bogaty język źródłowy do publikacji i konwersji.

Najbezpieczniejsza zasada jest prosta: pisz najmniejszy dialekt, który satysfakcjonuje rzeczywisty cel. Używaj CommonMark, gdy treść musi podróżować, GFM, gdy współpraca w stylu GitHub jest celem, i Pandoc Markdown, gdy struktura dokumentu i formaty wyjściowe mają większe znaczenie niż uniwersalne renderowanie.

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

Referencje

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