Formaty plików
Co to jest Markdown? Składnia, CommonMark i GFM
Markdown to lekki język znaczników, który kilkoma symbolami dodaje do zwykłego tekstu nagłówki, listy i linki. Omawiamy jego historię, normy i to, co zostaje po zamianie plików MD na Worda lub PDF.
Autor: Hemen Dönüştür Editör EkibiOpublikowano: 7 min czytania
Pomyśl o pliku README w projekcie programistycznym, o listach z nagłówkami w aplikacji do notatek albo o słowach, które pogrubiasz gwiazdkami w komunikatorze. Za wszystkimi stoi ten sam pomysł: Markdown. Markdown to lekki język znaczników, który pozwala definiować nagłówki, listy, linki i tabele przez dodanie do zwykłego tekstu kilku prostych symboli. Plik pozostaje czytelny w każdym edytorze tekstu, a w razie potrzeby można go zamienić na schludną stronę HTML, dokument Worda lub PDF. W tym artykule opisujemy, jak powstał Markdown, jego podstawową składnię, różnice między CommonMark a GitHub Flavored Markdown oraz to, na co uważać przy konwersji plików MD.
Czym jest Markdown?
Markdown to zarówno zestaw konwencji pisania, jak i potoczna nazwa narzędzi, które zamieniają tak napisany tekst na HTML. Pliki zapisuje się zwykle z rozszerzeniem .md lub .markdown. Według twórcy, Johna Grubera, nadrzędnym celem projektu jest czytelność: dokument Markdown powinien dać się opublikować w obecnej postaci, jako zwykły tekst, bez wrażenia, że oznaczono go znacznikami lub instrukcjami formatowania. Tam, gdzie HTML potrzebuje <strong>ważne</strong>, Markdown używa **ważne**, a nawet surowa wersja czyta się naturalnie.
Krótka historia
John Gruber stworzył Markdown w 2004 roku, a Aaron Swartz pomagał mu jako partner do dyskusji nad pomysłami. Składnia czerpała z konwencji znanych z e-maili w zwykłym tekście (gwiazdki do wyróżnień, łączniki do list) oraz z wcześniejszych języków znaczników, takich jak setext i Textile. Wersja 1.0.1 skryptu Markdown.pl w Perlu, który Gruber opublikował w swoim serwisie Daring Fireball, nosi datę 17 grudnia 2004 roku.
Opis Grubera był jednak wyjaśnieniem na przykładach, a nie formalną specyfikacją. Niejednoznaczne przypadki (zagnieżdżone listy, wcięte bloki kodu, mieszanie z HTML) sprawiły, że każda implementacja podejmowała własne decyzje, a ten sam tekst zaczął dawać różne wyniki w różnych narzędziach. Pojawiły się dwie główne odpowiedzi:
- CommonMark (2014): specyfikacja prowadzona przez Johna MacFarlane'a, która definiuje Markdown jednoznacznie i pozwala go testować na setkach przykładów. Pierwsze wersje ukazały się jesienią 2014 roku; aktualna wersja to 0.31.2 z 28 stycznia 2024 roku. Specyfikacja nie została jeszcze ogłoszona jako 1.0.
- GitHub Flavored Markdown (GFM, 2017): formalna specyfikacja GitHuba zbudowana na CommonMark. Dodaje rozszerzenia, takie jak tabele, listy zadań, przekreślenie, rozszerzone autolinki oraz, ze względów bezpieczeństwa, filtrowanie niektórych surowych znaczników HTML. Najnowsza opublikowana specyfikacja to 0.29-gfm z 6 kwietnia 2019 roku.
Markdown zyskał też uznanie w infrastrukturze internetu: RFC 7763, opublikowany w marcu 2016 roku, zarejestrował typ mediów (typ MIME) text/markdown z opcjonalnym parametrem variant, który wskazuje, jaki wariant Markdown miał na myśli autor.
Najważniejsze warianty Markdown
Poza CommonMark i GFM istnieją inne popularne warianty. RFC 7764, opublikowany razem z RFC 7763, zarejestrował kilka z nich i podał wskazówki dotyczące ich użycia:
- Markdown Extra: wczesne rozszerzenie, które dodało przypisy, listy definicji i tabele.
- MultiMarkdown: wariant przeznaczony do pisania akademickiego, z metadanymi, cytowaniami i odsyłaczami.
- Pandoc Markdown: wariant używany przez konwerter Pandoc, z wieloma rozszerzeniami do pisania książek i artykułów.
Praktyczna zasada: jeśli dokument używa tylko nagłówków, list, linków, kodu i prostych tabel, niemal wszędzie będzie wyglądał tak samo. Jeśli korzystasz z przypisów, list definicji lub specjalnych typów bloków, sprawdź, jaki wariant obsługuje środowisko docelowe.
Podstawowa składnia
Część Markdown potrzebną na co dzień można opanować w kilka minut:
# Nagłówek pierwszego poziomu
## Nagłówek drugiego poziomu
Ten akapit zawiera **pogrubienie**, *kursywę* i `kod`.
- Lista punktowana
- Drugi element
- Wcięty podpunkt
1. Lista numerowana
2. Drugi krok
[Tekst linku](https://example.com)
> Cytat blokowy
```
Wielowierszowy blok kodu
```Tabele i listy zadań, dodane przez GFM, wyglądają tak:
| Format | Rozszerzenie |
|--------|--------------|
| Markdown | .md |
| Zwykły tekst | .txt |
- [x] Napisać szkic
- [ ] Przejrzeć goAkapity oddziela się pustymi wierszami. Pojedynczy podział wiersza w większości implementacji jest traktowany jako część tego samego akapitu; aby wymusić złamanie wiersza, zakończ wiersz dwiema spacjami. W Markdown można też pisać bezpośrednio HTML. CommonMark na to pozwala, choć środowiska takie jak GFM ze względów bezpieczeństwa blokują niektóre znaczniki.
Gdzie używa się Markdown?
- Tworzenie oprogramowania: pliki README, dzienniki zmian i wytyczne dla współtwórców, a także zgłoszenia i komentarze do przeglądu kodu na platformach takich jak GitHub i GitLab.
- Dokumentacja techniczna: generatory stron statycznych, które budują witryny z plików Markdown.
- Notatki: wiele aplikacji do notatek przechowuje lub eksportuje notatki jako Markdown.
- Komunikatory i platformy społecznościowe: platformy takie jak Reddit i Discord używają wariantów Markdown.
- Pisanie i publikowanie: tworzenie HTML, PDF, DOCX i EPUB z jednego źródła Markdown za pomocą narzędzi takich jak Pandoc.
- Narzędzia AI: asystenci AI oparci na czacie często formatują odpowiedzi w Markdown.
Zalety i wady
| Zalety | Wady |
|---|---|
| Czytelny nawet w surowej postaci | Warianty zachowują się różnie |
| Zwykły tekst: mały, przenośny, przyjazny kontroli wersji | Brak czcionek, kolorów i układu strony |
| Łatwo zamienia się na HTML, PDF i Worda | Brak złożonych tabel (scalonych komórek) |
| Do opanowania w kilka minut | Obrazy są w osobnych plikach |
| Niezwiązany z żadnym programem | Błędy w odstępach i wcięciach zmieniają wynik |
Jakie programy otwierają Markdown?
Ponieważ Markdown to zwykły tekst, otwiera się w każdym edytorze tekstu, także w Notatniku i TextEdit. Do sformatowanego podglądu możesz użyć wbudowanego podglądu Markdown w Visual Studio Code albo dedykowanych edytorów, takich jak Obsidian i Typora. GitHub i GitLab automatycznie renderują pliki .md w repozytoriach. Word natomiast nie otwiera Markdown jako sformatowanego tekstu, więc najpierw trzeba plik przekonwertować.
Typowe problemy i jak je rozwiązać
Lista lub nagłówek się nie renderuje
CommonMark wymaga spacji po znaczniku nagłówka: ## Nagłówek, a nie ##Nagłówek. Lista następująca po akapicie często też potrzebuje pustego wiersza przed sobą, żeby wyświetlić się poprawnie.
Wiersze zlewają się ze sobą
Pojedynczy podział wiersza nie dzieli akapitu. Zostaw pusty wiersz, aby zacząć nowy akapit, albo zakończ wiersz dwiema spacjami, aby złamać go w obrębie akapitu.
Tabela działa na jednej platformie, a na innej nie
Tabele nie należą ani do oryginalnego Markdown Grubera, ani do rdzenia CommonMark; pochodzą z rozszerzeń, takich jak GFM. Sprawdź, jaki wariant obsługuje platforma docelowa.
Akapit zaczynający się od liczby zamienia się w listę numerowaną
Wiersz taki jak „2024. był pracowitym rokiem” zaczyna się od cyfr i kropki, więc może zostać zinterpretowany jako lista. Aby temu zapobiec, poprzedź kropkę ukośnikiem wstecznym (2024\.).
Wskazówki dotyczące konwersji plików Markdown
W naszym konwerterze pliki Markdown są wysyłane na nasz serwer i usuwane w ciągu 30 minut. Do odczytu używamy biblioteki Markdig z CommonMark i rozszerzeniami w stylu GitHuba (tabele, listy zadań, przypisy, autolinki).
- Markdown do PDF i Markdown do Worda zachowują nagłówki, listy, bloki kodu, cytaty blokowe i tabele z obramowaniem. Pola wyboru z list zadań są zamieniane na znaki ☑ i ☐, żeby pozostały widoczne w Wordzie i PDF. Tekst jest domyślnie składany szeryfową czcionką 12 pt, a bloki kodu czcionką o stałej szerokości.
- Markdown do HTML zamienia README w samodzielną stronę internetową z zadeklarowanym kodowaniem znaków.
- W drugą stronę Word do Markdown, HTML do Markdown i PDF do Markdown tworzą Markdown zgodny z GitHubem: nagłówki, pogrubienie i kursywa, listy, tabele, linki, bloki kodu i cytaty blokowe są zachowywane; czcionki, kolory i układ strony znikają. W tabelach bez wiersza nagłówka pierwszy wiersz staje się nagłówkiem, bo tabele GFM go wymagają. Zwykłe akapity zaczynające się od liczby, na przykład „1. Postanowienie”, są poprzedzane znakiem ucieczki, żeby przypadkiem nie stały się listami. Plik jest zapisywany jako UTF-8 bez BOM.
Najczęściej zadawane pytania
Jak otworzyć plik MD?
Otworzy go każdy edytor tekstu. Aby zobaczyć go sformatowanego, użyj podglądu w Visual Studio Code lub edytora Markdown; jeśli chcesz go czytać w Wordzie, przekonwertuj go do DOCX.
Czym różni się CommonMark od GitHub Flavored Markdown?
CommonMark definiuje podstawową składnię Markdown za pomocą precyzyjnych reguł. GFM to nadzbiór, który dodaje do CommonMark rozszerzenia, takie jak tabele, listy zadań, przekreślenie i rozszerzone autolinki.
Czy w Markdown można tworzyć tabele?
Tak, z rozszerzeniami takimi jak GFM możesz pisać proste tabele za pomocą pionowych kresek i łączników. Do złożonych struktur, takich jak scalone komórki, użyj tabeli HTML albo przygotuj dokument w Wordzie.
Czym różni się Markdown od HTML?
Markdown to prostszy format pisania, zaprojektowany z myślą o zamianie na HTML. Nie wyrazi wszystkiego, co HTML, ale jego surowa postać jest znacznie czytelniejsza. W razie potrzeby nadal możesz pisać HTML wewnątrz Markdown.
Czy Markdown ma oficjalną normę?
Oryginalny opis Grubera nie jest formalną specyfikacją. Najszerzej przyjętą precyzyjną definicją jest dziś CommonMark, a typ mediów text/markdown został zarejestrowany przez RFC 7763 w marcu 2016 roku.
