Piszesz dokumentację projektu, notatki z meetingu albo opis do repozytorium i za każdym razem zastanawiasz się, czy sięgnąć po edytor WYSIWYG, surowy HTML czy zwykły plik tekstowy. Markdown rozwiązuje ten dylemat inaczej: formatujesz tekst znakami, które w surowej postaci są czytelne dla człowieka, a po renderowaniu stają się pełnoprawnym HTML-em. Markdown to lekki język znaczników opracowany w 2004 roku przez Johna Grubera, który od tamtej pory stał się standardem w dokumentacji technicznej, repozytoriach kodu i narzędziach do pisania notatek. Pliki mają rozszerzenie `.MD` i można je otworzyć w dowolnym edytorze tekstowym, niezależnie od systemu operacyjnego. Żadnego formatu własnościowego, żadnego ryzyka, że za trzy lata plik przestanie się otwierać.
Ten przewodnik scala treść kilku dawnych wpisów o Markdown w jeden dokument. Znajdziesz tu zarówno podstawy składni, jak i informacje o narzędziach, wariantach standardu i praktycznych zastosowaniach.
Czym jest Markdown i czym różni się od HTML oraz WYSIWYG?
Edytor WYSIWYG (ang. What You See Is What You Get) ukrywa znaczniki za interfejsem graficznym. Klikasz przycisk „pogrubienie” i tekst staje się pogrubiony, ale pod spodem powstaje kod, którego nie widzisz. HTML robi odwrotnie: znaczniki są widoczne, lecz surowy plik jest trudny do czytania bez renderowania. Markdown zajmuje inne miejsce w tym spektrum. Surowy plik tekstowy pozostaje czytelny, bo znaki formatowania są intuicyjne: gwiazdki wokół słowa oznaczają kursywę, kratka na początku linii to nagłówek.
Kluczowa różnica między Markdown a HTML polega na tym, że Markdown jest konwertowany do HTML przez parser, a nie pisany bezpośrednio jako HTML. Oznacza to, że możesz skupić się na treści, a nie na zamykaniu tagów. W praktyce jednak Markdown i HTML nie wykluczają się wzajemnie: większość parserów akceptuje wstawiony inline HTML tam, gdzie Markdown nie ma odpowiedniej składni.
Pliki `.MD` nadają się do kontroli wersji znacznie lepiej niż dokumenty z edytorów biurowych. Są małe, szybko się ładują, a różnice między wersjami są czytelne w narzędziach takich jak Git. To dlatego Markdown stał się standardem w dokumentacji API, przewodnikach użytkownika i wiki projektowych. Natywnie obsługują go GitHub, GitLab, Reddit, Discord i Stack Overflow.
Podstawowa składnia formatowania tekstu
Formatowanie znakami to rdzeń Markdown. Pogrubienie uzyskujesz, otaczając tekst podwójnymi gwiazdkami: `tekst` lub podwójnymi podkreślnikami `__tekst__`. Kursywa działa analogicznie, ale z jednym znakiem: `tekst` albo `_tekst_`. Połączenie obu daje pogrubioną kursywę: `tekst`. Warto konsekwentnie trzymać się jednej konwencji w obrębie dokumentu, bo mieszanie gwiazdek i podkreślników może powodować nieoczekiwane wyniki w niektórych parserach.
Przekreślenie to rozszerzenie standardu, niedostępne w każdym parserze. Zapisuje się je podwójnymi tyldami: `~~tekst~~`. Jeśli pracujesz w środowisku, które korzysta z CommonMark jako bazowej specyfikacji, sprawdź dokumentację przed użyciem.
Kod w tekście otacza się pojedynczymi grawisami: „ `kod` „. Blok kodu wymaga potrójnych grawisów na początku i końcu fragmentu. Po otwierającym „` można podać nazwę języka, np. `python` lub `javascript`, co włącza podświetlanie składni w parserach, które je obsługują. To rozróżnienie ma znaczenie praktyczne: kod inline stosuje się do nazw funkcji i zmiennych wplecionych w zdanie, blok kodu do dłuższych fragmentów wymagających zachowania wcięć.
Akapity i łamanie linii to miejsce, gdzie Markdown zachowuje się inaczej, niż większość użytkowników oczekuje. Pojedynczy znak nowej linii nie łamie wiersza: parser łączy sąsiednie linie w jeden akapit. Nowy akapit powstaje dopiero przez pustą linię między fragmentami tekstu. Jeśli chcesz wymusić złamanie linii wewnątrz akapitu, dopisz dwie spacje na końcu wiersza lub wstaw znacznik HTML `
`. Linia pozioma powstaje z trzech lub więcej myślników (`—`), gwiazdek (`***`) albo podkreślników (`___`).
Strukturyzowanie treści nagłówkami i cytatami
Nagłówki tworzy się znakiem `#` przed tekstem. Liczba znaków `#` od 1 do 6 określa poziom nagłówka i odpowiada tagom H1–H6 w HTML. Jeden `#` to nagłówek pierwszego poziomu, sześć `######` to szósty. Istnieje alternatywna składnia: podkreślenie tekstu znakami `===` daje nagłówek pierwszego poziomu, a myślnikami `—` nagłówek drugiego. Obsługują ją jednak tylko niektóre implementacje, więc w projektach wymagających przenośności lepiej trzymać się składni kratowej.
Ważna zasada: nie pomijaj poziomów hierarchii. Po nagłówku H2 powinien następować H3, nie H5. Pomijanie poziomów psuje strukturę dokumentu w czytnikach ekranowych i narzędziach generujących spis treści.
Cytat blokowy tworzy się znakiem `>` na początku linii. Zagnieżdżony cytat wymaga dwóch znaków: `>>`. Wewnątrz cytatu możesz używać nagłówków, list i formatowania tekstu, co pozwala budować złożone struktury tam, gdzie to potrzebne. Cytaty zagnieżdżone przydają się przy dokumentowaniu wątków dyskusji lub odpowiedzi na odpowiedź w przeglądach kodu.
Hierarchia nagłówków w Markdown bezpośrednio przekłada się na strukturę HTML, co ma znaczenie dla parserów generujących spis treści oraz dla narzędzi do konwersji dokumentów. Pandoc, który konwertuje Markdown do HTML, PDF, Word, LaTeX i EPUB, używa tej hierarchii do budowania struktury dokumentu wyjściowego. Jeśli nagłówki są chaotyczne, wynikowy PDF lub dokument Word będzie miał równie chaotyczną strukturę.
Listy, linki i obrazy w praktyce
Listy nieuporządkowane tworzy się myślnikiem, gwiazdką lub znakiem `+` przed tekstem elementu. Wszystkie trzy znaki działają tak samo, choć w obrębie jednego dokumentu warto trzymać się jednego. Lista uporządkowana wymaga cyfry i kropki: `1.`, `2.`, `3.`. Ciekawostka, którą warto znać: parser nie wymaga, żebyś numerował kolejno. Możesz napisać `1.` dla każdego elementu, a HTML wyjściowy i tak wyświetli `1`, `2`, `3`. To przydatne przy długich listach, gdzie ręczna renumeracja byłaby uciążliwa.
Wcięcie decyduje o zagnieżdżeniu. Cztery spacje lub jeden tabulator przesuwają element na poziom niżej. Możesz mieszać typy list: lista nieuporządkowana może zawierać zagnieżdżoną listę uporządkowaną i odwrotnie. Głębokość zagnieżdżenia nie jest formalnie ograniczona, jednak w praktyce więcej niż dwa poziomy utrudnia czytanie zarówno w źródle, jak i po renderowaniu.
Poniżej zestawiono cztery rozszerzenia list, które pojawiają się najczęściej w projektach i warto je znać przed wyborem parsera:
- listy zadań – składnia `- [ ]` tworzy niezaznaczone pole wyboru, `- [x]` zaznaczone; w repozytoriach GitHub takie listy w opisach zgłoszeń są klikalne;
- GitHub Flavored Markdown – obsługuje listy zadań natywnie, podobnie jak wiele innych implementacji poza oryginalną specyfikacją Grubera;
- zagnieżdżone listy mieszane – lista nieuporządkowana może zawierać zagnieżdżoną listę uporządkowaną i odwrotnie, bez formalnego limitu głębokości;
- renumeracja automatyczna – pisanie `1.` dla każdego elementu zamiast kolejnych cyfr upraszcza edycję długich list, bo parser sam generuje właściwe numery.
Linki w Markdown mają dwa warianty. Pierwszy, inline, wygląda tak: `[tekst linku](URL)`. Drugi, referencyjny, rozdziela tekst od adresu: w treści piszesz `[tekst][etykieta]`, a gdzieś dalej w dokumencie definiujesz `[etykieta]: URL`. Ten drugi wariant sprawdza się w długich dokumentach, gdzie ten sam adres pojawia się wielokrotnie: zmiana URL w jednym miejscu aktualizuje wszystkie odwołania. Oba warianty obsługują opcjonalny tytuł wstawiany w cudzysłowie po adresie, który pojawia się jako podpowiedź po najechaniu kursorem.
Obrazy działają niemal identycznie jak linki, ale ze znakiem wykrzyknika na początku: ``. Tekst alternatywny wewnątrz nawiasów kwadratowych to nie ozdoba, lecz opis dla czytników ekranowych i dla sytuacji, gdy obraz nie ładuje się. Pomijanie go to błąd dostępności, który w projektach publicznych może mieć realne konsekwencje. Markdown nie oferuje natywnej kontroli nad rozmiarem ani wyrównaniem obrazu: jeśli potrzebujesz takich opcji, musisz wstawić znacznik HTML `` z atrybutami `width` i `height`.
Tabele, kod i rozszerzenia składni
Tabele nie należą do oryginalnej specyfikacji Johna Grubera z 2004 roku. Pojawiły się jako rozszerzenie i dziś obsługuje je większość popularnych implementacji, w tym GitHub Flavored Markdown, Pandoc i kramdown. Składnia opiera się na pionowych kreszkach oddzielających kolumny i wierszu z myślnikami pod nagłówkiem:
„`
| Kolumna A | Kolumna B |
|---|---|
| wartość 1 | wartość 2 |
„`
Wyrównanie zawartości kolumny kontroluje się dwukropkiem w wierszu separatora. Dwukropek po lewej stronie myślników wyrównuje do lewej, po prawej – do prawej, z obu stron centruje. Edytory takie jak Typora automatycznie wyrównują pionowe kreski, żeby tabela była czytelna w surowym pliku. W edytorach bez tego wsparcia tabela w źródle wygląda chaotycznie, choć renderuje się poprawnie.
Tabele Markdown mają jedno istotne ograniczenie: nie obsługują scalania komórek. Jeśli potrzebujesz złożonego układu z komórkami rozciągającymi się na kilka kolumn lub wierszy, jedynym wyjściem jest HTML wstawiony bezpośrednio w dokument. Większość parserów przepuszcza HTML bez modyfikacji, co daje ucieczkę od ograniczeń składni, ale kosztem czytelności źródła.
Podświetlanie składni w blokach kodu to funkcja zależna od parsera i środowiska renderowania. Sam Markdown nie definiuje, jak ma wyglądać podświetlony kod: określa tylko, że po otwierających grawisach można podać identyfikator języka. To, co dalej się dzieje z tym identyfikatorem, zależy od narzędzia. GitHub używa biblioteki Linguist do rozpoznawania ponad 500 języków. Pandoc z odpowiednim filtrem generuje podświetlony kod w PDF przez LaTeX. Statyczne generatory stron jak Jekyll czy Hugo integrują własne biblioteki podświetlania. Jeśli piszesz dokumentację techniczną przeznaczoną do wielu formatów wyjściowych, warto sprawdzić z wyprzedzeniem, które identyfikatory języków obsługuje twój parser.
Wśród popularnych rozszerzeń składni warto znać cztery, które pojawiają się najczęściej w projektach. Przekreślenie tekstu realizuje się podwójną tyldą: `~~tekst~~`. Indeks górny i dolny obsługuje na przykład Pandoc przez `^tekst^` i `~tekst~`, ale GitHub już nie. Definicje w stylu słownikowym, gdzie termin i jego opis oddzielone są dwukropkiem, to funkcja kramdown i MultiMarkdown. Przypis dolny wymaga składni `[^1]` w tekście i `[^1]: treść` w innym miejscu dokumentu, co obsługuje Pandoc i kilka innych implementacji, lecz nie GitHub.
Matematyka to osobny temat. Wiele środowisk dokumentacyjnych i platform edukacyjnych integruje LaTeX przez bibliotekę MathJax lub KaTeX. Wzory inline wstawia się między pojedyncze znaki dolara: `$E=mc^2$`, wzory blokowe między podwójne: `$$`. To nie jest część żadnej standardowej specyfikacji Markdown, ale w praktyce stało się de facto standardem w dokumentach naukowych i technicznych pisanych w tym formacie.
Gdzie i jak stosować Markdown w pracy
Wybór narzędzia, w którym piszesz Markdown, ma większe znaczenie, niż mogłoby się wydawać. Zwykły edytor tekstowy jak Notepad++ lub Vim obsługuje pliki `.MD` bez żadnej specjalnej obsługi: widzisz surowy tekst ze znakami formatowania. Edytory dedykowane, takie jak Typora, Obsidian czy iA Writer, renderują wynik na bieżąco lub w podzielonym widoku. Obsidian przechowuje wszystkie notatki jako pliki `.MD` na dysku lokalnym, co oznacza pełną kontrolę nad danymi i łatwą migrację: 10 000 notatek to po prostu 10 000 plików tekstowych.
Repozytoria Git to środowisko, w którym Markdown sprawdza się szczególnie dobrze. Plik `README.MD` w katalogu głównym repozytorium jest automatycznie renderowany przez GitHub, GitLab i Bitbucket jako strona powitalna projektu. Dokumentacja techniczna pisana w Markdown razem z kodem źródłowym podlega tym samym procesom recenzji: zmiany w dokumentacji widać w diff, historia edycji jest pełna, a konflikty można rozwiązywać tymi samymi narzędziami co konflikty w kodzie.
Statyczne generatory stron takie jak Hugo, Jekyll czy Eleventy przyjmują pliki Markdown jako źródło treści i na ich podstawie budują gotowe strony HTML. Hugo przetwarza tysiące stron w czasie poniżej sekundy, co sprawia, że nawet rozbudowane serwisy dokumentacyjne można budować bez bazy danych i bez serwera aplikacyjnego. Treść pozostaje w plikach tekstowych, szablon i logika prezentacji są osobno.
Markdown w pracy – pułapki i dobre praktyki
Nawet jeśli składnia jest prosta, kilka błędów pojawia się regularnie i może kosztować sporo czasu. Najczęstszy dotyczy pustych linii: w Markdown brak pustej linii między akapitem a listą, nagłówkiem lub blokiem kodu sprawia, że parser traktuje całość jako jeden ciągły blok tekstu. Wynik w przeglądarce wygląda inaczej niż w edytorze, a przyczyna nie jest od razu oczywista.
Drugi problem to mieszanie konwencji z różnych implementacji w jednym projekcie. Jeśli piszesz dokumentację, która będzie renderowana przez MkDocs, a testujesz podgląd w Typora, możesz natknąć się na rozbieżności w obsłudze tabel, przypisów dolnych lub bloków ostrzeżeń (admonition). Ustal jeden parser dla całego projektu i trzymaj się go od początku.
Przenośność plików to mocna strona formatu, ale tylko przy zachowaniu kilku zasad. Obrazy osadzone przez ścieżki względne (`./obrazy/schemat.png`) działają lokalnie, lecz przestają działać po przeniesieniu katalogu. Zasoby warto trzymać w podkatalogu przy pliku Markdown, a nie w miejscu zależnym od struktury serwera. Linki wewnętrzne między plikami `.MD` obsługuje większość generatorów stron, ale składnia różni się między Hugo a Jekyll, więc migracja między narzędziami może wymagać masowej zamiany ścieżek.
Dla zespołów piszących dokumentację równolegle przydatny jest linter Markdown – narzędzie sprawdzające spójność formatowania. `markdownlint` dostępny jako wtyczka do VS Code lub jako narzędzie CLI oznacza niespójne nagłówki, brakujące puste linie i inne odchylenia od przyjętego stylu. Przy kilkudziesięciu plikach utrzymywanych przez kilka osób różnice w formatowaniu narastają szybko.
Czy Markdown to właściwy wybór dla twojego projektu?
Markdown sprawdza się wszędzie tam, gdzie treść żyje dłużej niż jedno użycie i musi działać w różnych kontekstach – jako strona HTML, plik PDF, slajdy albo fragment dokumentacji w repozytorium. Jeśli piszesz tekst, który trafi tylko do jednego systemu i nigdy go nie wyeksportujesz, korzyść z formatu tekstowego jest mniejsza.
Warto też pamiętać, że Markdown nie rozwiązuje problemu struktury treści, tylko problem jej formatowania. Dobrze napisany dokument w Markdown nadal wymaga przemyślanej hierarchii nagłówków, logicznego podziału na sekcje i precyzyjnego języka. Format jest narzędziem, nie substytutem redakcji.
Pytanie, które warto sobie zadać przed wyborem: czy za rok będziesz w stanie otworzyć ten plik w dowolnym edytorze tekstowym i od razu zrozumieć jego strukturę bez żadnych wtyczek ani specjalnego oprogramowania?
