Markdown od podstaw: poradnik i ściągawka

Markdown to sposób formatowania zwykłego tekstu za pomocą kilku prostych znaków. # na początku wiersza tworzy nagłówek, **dwie gwiazdki** pogrubiają tekst, a - ze spacją zaczyna punkt listy. Aplikacja odczytuje te znaki i wyświetla sformatowany tekst, a sam zapis pozostaje czytelny nawet w najprostszym edytorze.

W tym poradniku pokazujemy podstawową składnię na przykładach z codziennych notatek: nagłówki, listy, linki, obrazy i bloki kodu. Na końcu znajdziesz ściągawkę i sposoby na najczęstsze problemy.

Markdown: co to jest?

Markdown to język znaczników, czyli zapis, w którym określone znaki opisują strukturę tekstu i wyróżnienia. W HTML pogrubienie zapisuje się jako <strong>mleko</strong>, a w Markdownie jako **mleko**. Nie trzeba ręcznie ustawiać wyglądu każdego elementu.

Markdown opublikował w 2004 roku John Gruber, a nad składnią pracował z nim Aaron Swartz. Na stronie projektu Gruber pisze, że najważniejsza jest czytelność: tekst ma być zrozumiały, jeszcze zanim zostanie zamieniony na HTML.

Jeden język, kilka dialektów

Pierwotny opis Grubera nie rozstrzygał wszystkich szczegółów, więc różne programy zaczęły odczytywać ten sam tekst nieco inaczej. Żeby to uporządkować, grupa programistów przygotowała CommonMark, czyli dokładną specyfikację podstawowej składni. Aktualna wersja (stan na wrzesień 2026 roku) to 0.31.2 ze stycznia 2024 roku.

Na tej specyfikacji GitHub oparł GitHub Flavored Markdown (GFM). Ten wariant dodaje tabele, listy zadań z polami wyboru, przekreślenie i automatyczne linki. Większość aplikacji do notatek obsługuje CommonMark, całość lub część GFM i do tego własne dodatki, na przykład zakreślacz albo linki między notatkami.

Odmiana Markdowna

Zestaw podstawowych reguł i rozszerzeń, które obsługuje dany program. Wspólna składnia ułatwia przenoszenie tekstu, ale dodatki, takie jak wzory czy wikilinki, mogą wymagać osobnej obsługi.

Podstawową składnię obsługuje większość programów, ale przy przenoszeniu notatek warto sprawdzić, czy nowy program rozumie te same rozszerzenia. W poradniku o tabelach, zadaniach, wzorach i diagramach zaznaczamy, co należy do GFM, a co zależy od aplikacji.

Dlaczego warto pisać notatki w Markdownie?

Aplikacje z edytorem wizualnym mogą zapisywać formatowanie we własnych strukturach danych. W Markdownie znaki formatowania są częścią tekstu, więc łatwo zajrzeć do pliku i przenieść jego treść do innego programu. Nie każdy program wyświetli jednak rozszerzenia tak samo.

Plik MD: co to jest?

Plik .md to zwykły plik tekstowy, który różni się od innych tylko rozszerzeniem nazwy. Od 2016 roku ma nawet oficjalnie zarejestrowany typ text/markdown (RFC 7763). Otworzysz go edytorem wbudowanym w system (Notatnikiem w Windows, TextEditem na Macu) albo dowolnym edytorem kodu.

Zwykły tekst odczyta niemal każdy program. Nawet jeśli aplikacja przestanie działać, wyeksportowane pliki .md otworzysz w innym edytorze, o ile zachowasz same pliki i ich załączniki. Podobny nacisk na kontrolę nad własnymi danymi kładzie podejście local-first, choć to, że aplikacja używa Markdowna, nie przesądza jeszcze, jak działa.

Jak pisać w Markdownie: podstawy

W przykładach zapis źródłowy stoi obok efektu, a na telefonie nad nim. Możesz skopiować składnię do własnego edytora i sprawdzić, jak ją wyświetla.

Nagłówki

Zacznij wiersz od jednego do sześciu znaków # i spacji. Jeden # oznacza największy nagłówek, zwykle tytuł notatki, dwa oznaczają sekcję, trzy podsekcję i tak dalej.

# Wyjazd na Hel
## Co spakować
### Dokumenty

Spacja po # jest konieczna: według CommonMark #Dokumenty to zwykły tekst, a nie nagłówek. W większości notatek wystarczą dwa albo trzy poziomy.

Akapity i łamanie wierszy

Nowy akapit oddziel pustym wierszem. Pojedynczy Enter zwykle łamie wiersz tylko w zapisie źródłowym, a w podglądzie może się zamienić w spację.

Zadzwonić do dentysty
Kupić bilet na pociąg

Zapytać Anię o sobotę

Dwa pierwsze wiersze należą tu do jednego akapitu. Jeśli chcesz przejść do nowego wiersza w obrębie akapitu, np. w adresie, zakończ poprzedni wiersz ukośnikiem wstecznym \. Można też zostawić na jego końcu dwie spacje, ale taki zapis łatwo przeoczyć.

Anna Nowak\
ul. Długa 12\
80-827 Gdańsk

Pogrubienie, kursywa i przekreślenie

Tekst otoczony pojedynczymi gwiazdkami będzie kursywą, podwójnymi pogrubieniem, a potrójnymi jednym i drugim. Działają też podkreślniki (_kursywa_, __pogrubienie__), ale lepiej przyzwyczaić się do gwiazdek, bo działają również w środku wyrazu. Przekreślenie zapisuje się dwiema tyldami. Pochodzi z GFM, a nie z CommonMark, ale obsługuje je większość aplikacji.

Lot jest *chyba* w **piątek**.
Wylot o ***6:40 rano***.
~~Wziąć taksówkę~~ Pojechać SKM-ką.

Listy

Listę punktowaną tworzysz, zaczynając każdy wiersz od -, * albo + i spacji. Wybierz jeden znak i używaj go konsekwentnie; najczęściej spotyka się -. Punkt listy numerowanej to liczba, kropka i spacja.

- Dowód osobisty
- Ładowarka
- Krem z filtrem

1. Odprawa online
2. Wydruk karty pokładowej
3. Wyjście z domu o 5:30

Według CommonMark pierwsza liczba wyznacza początek numeracji, a kolejne numery program nadaje sam. Dlatego zapis 1., 1., 1. może się wyświetlić jako 1, 2, 3, a po przestawieniu punktów nie trzeba ręcznie poprawiać numerów.

Aby utworzyć podlistę, dodaj przed podpunktem odpowiednie wcięcie, tak by zaczynał się pod tekstem punktu nadrzędnego. W prostych przykładach poniżej wystarczą cztery spacje, ale przy długich numerach wcięcie musi być większe. W wielu edytorach poziom punktu zmienia się klawiszem Tab.

- Ubrania
    - Lekka kurtka
    - Wygodne buty
- Kosmetyki
    - Szczoteczka do zębów

Linki

Tekst linku wpisz w nawiasy kwadratowe, a adres zaraz za nim w nawiasy okrągłe: [opis](adres). Sam adres możesz ująć w nawiasy ostre.

Bilety są na [stronie muzeum](https://www.example.com/bilety).
Godziny otwarcia: <https://www.example.com/godziny>

Niektóre aplikacje, np. te, które obsługują automatyczne linki z GFM, rozpoznają też sam adres zaczynający się od https://. Zapis w nawiasach ostrych należy natomiast do podstawowej składni. Linki w postaci [[Tytuł notatki]] to rozszerzenie, które opisujemy w dalszej części poradnika.

Obrazy

Obraz zapisuje się tak jak link, tylko z wykrzyknikiem na początku. W nawiasach kwadratowych wpisujesz tekst alternatywny: krótki opis, który czytnik ekranu przeczyta na głos i który pojawi się, gdy obrazek się nie wczyta.

Piszesz

![Kapibara siedząca nad stawem](/illustrations/empty-notes.png)

Widzisz

Plik Markdown wskazuje, gdzie leży obraz, ale zwykle nie zawiera samego obrazu. Przenosząc notatki, skopiuj też obrazy i zadbaj o poprawne ścieżki. Obraz z adresu w internecie może wymagać połączenia z cudzym serwerem, a to, kiedy aplikacja go pobiera i czy zachowuje kopię, zależy od aplikacji.

Cytaty

Wiersz zaczynający się od > to cytat. Tak przytoczysz czyjeś słowa albo wyodrębnisz ważną myśl. Każdy wiersz dłuższego cytatu może zaczynać się od >, a wiersz z samym > pozwala dodać w cytacie kolejny akapit.

> Pakuj się lekko.
> I tak coś tam kupisz.
>
> (Babcia, przed każdym wyjazdem)

Kod w tekście i bloki kodu

Krótki fragment kodu, nazwę pliku albo polecenie otocz pojedynczymi grawisami (odwrotnymi apostrofami): `notatki.md`. Blok kilku wierszy zacznij od wiersza z trzema grawisami i takim samym wierszem go zakończ. Po otwierających grawisach możesz podać nazwę języka programowania; niektóre aplikacje kolorują wtedy składnię.

Zmień nazwę pliku na `notatki.md`.

```
git add notatki.md
git commit -m "Pierwsza notatka"
```

git add notatki.md
git commit -m "Pierwsza notatka"

Znaki Markdowna wewnątrz fragmentu lub bloku kodu nie działają jako formatowanie. Dlatego w ten sposób wygodnie zapisuje się polecenia, nazwy plików i przykłady składni.

Na polskiej klawiaturze programisty grawis leży na lewo od klawisza 1, a tyldę daje ten sam klawisz z Shiftem. W Windows tylda bywa klawiszem martwym: jeśli nie pojawi się od razu, naciśnij po niej spację.

Linia pozioma

Trzy łączniki, gwiazdki albo podkreślniki w osobnym wierszu tworzą poziomą linię. Nad --- zostaw pusty wiersz, bo trzy łączniki tuż pod tekstem zamieniają ten tekst w nagłówek (to starszy styl nagłówków, tzw. setext).

Plan na rano

---

Plan na popołudnie

Wyłączanie formatowania

Jeśli znak interpunkcyjny ma zostać wyświetlony dosłownie, poprzedź go ukośnikiem wstecznym \. Dotyczy to m.in. gwiazdki, podkreślnika, znaku #, nawiasów kwadratowych i kropki.

18\. urodziny Kuby: kupić prezent
Pomnóż 2\*3\*4.
\# to nie jest nagłówek

Bez ukośników pierwszy wiersz zmieniłby się w listę numerowaną od 18, gwiazdki zamieniłyby trójkę w kursywę, a ostatni wiersz stałby się nagłówkiem. Liczba z kropką na początku wiersza to w polszczyźnie częsta pułapka, bo liczebniki porządkowe zapisujemy z kropką: „18. urodziny”, „3. piętro”.

Ściągawka Markdown: wszystko w jednej tabeli

W tabeli zebraliśmy podstawowe znaki. Tam, gdzie to możliwe, kolumna „Efekt” pokazuje wynik, a gdzie wynik nie zmieściłby się w komórce, opisuje go słowami.

Najczęstsze błędy w Markdownie i jak je naprawić

Większość poniższych problemów bierze się ze spacji i pustych wierszy albo z różnic między odmianami Markdowna.

Jak pisać w Markdownie szybciej?

Kilka znaków i skrótów klawiszowych pozwala formatować tekst bez sięgania do menu.

Zaczynaj wiersz od właściwego znaku. - rozpoczyna listę punktowaną, 1. listę numerowaną, a > cytat.

Sprawdź, czy edytor sam kontynuuje listy. W wielu edytorach Enter dodaje kolejny punkt, a Enter w pustym punkcie kończy listę. Tab i Shift+Tab często zmieniają poziom zagnieżdżenia.

Korzystaj ze znanych skrótów. W większości aplikacji do notatek w Markdownie, w tym w Obsidianie i Bearze, ⌘/Ctrl B pogrubia tekst, a ⌘/Ctrl I zamienia go w kursywę. Gwiazdki wokół zaznaczenia aplikacja wstawia sama.

Wklejaj adres na zaznaczony tekst. Edytory, które mają tę funkcję, od razu tworzą link [zaznaczony tekst](adres).

Dbaj o przejrzystą strukturę. Długi tekst podziel nagłówkami, a notatkom o różnych sprawach nadawaj konkretne tytuły. Jak uporządkować większy zbiór, opisujemy w artykule o organizowaniu notatek.

Markdown w Cappie

Cappa, aplikacja zespołu, który prowadzi ten blog, zapisuje każdą notatkę jako tekst w Markdownie. Edytor pokazuje podgląd na żywo: formatowanie pojawia się w trakcie pisania, a znaki Markdowna chowają się, gdy kursor jest gdzie indziej. Wystarczy wejść kursorem w pogrubione słowo, a gwiazdki ** wrócą i będzie można je poprawić. Jeśli wolisz widzieć wszystkie znaki przez cały czas, włącz w ustawieniach opcję Show Markdown syntax.

Jeśli przenosisz notatki z Cappy do innego programu, pamiętaj o kilku różnicach:

• Podstawy są standardowe. Nagłówki, wyróżnienia, listy, linki, obrazy, cytaty, kod i linie poziome działają zgodnie z CommonMark, a tabele, listy zadań i przekreślenie zgodnie z GFM.
• Część dodatków działa tak jak w Bearze. W Cappie ~tekst~ oznacza podkreślenie, ==tekst== wyróżnienie tłem, a #podróże tag. Inne programy mogą odczytać te znaki inaczej (np. pojedynczą tyldę jako przekreślenie) albo pokazać je dosłownie.
• Wiersze zostają tam, gdzie je wpiszesz. Jak większość edytorów z podglądem na żywo, Cappa pokazuje każdy wiersz osobno. Jeśli notatka ma być czytana w innym programie, oddzielaj akapity pustymi wierszami.
• Eksport zachowuje tekst źródłowy. Jedną lub wiele notatek możesz wyeksportować do osobnych plików Markdown albo TXT. Cappa importuje też takie pliki i całe foldery.

Cappa to prywatna aplikacja typu local-first: notatki są szyfrowane w przeglądarce, zanim trafią do synchronizacji. Sam Markdown się przez to nie zmienia. Wyeksportowany plik .md to zwykły, czytelny tekst, więc przechowuj go w bezpiecznym miejscu.

Co dalej?

Jeśli potrzebujesz bardziej rozbudowanej struktury, zajrzyj do poradnika o tabelach, listach zadań, przypisach, wzorach i diagramach. Jak uporządkować cały zbiór notatek, opisujemy w porównaniu metod Zettelkasten i PARA.

Najczęstsze pytania

Czy Markdown jest trudny do nauczenia?

Nie. Do zwykłych notatek wystarczy kilka znaków: nagłówki, listy, pogrubienie i linki. Resztę możesz poznawać w miarę potrzeb. Na początku warto przećwiczyć różnicę między pojedynczym Enterem a pustym wierszem.

Plik MD: co to jest i jak go otworzyć?

Plik .md to zwykły plik tekstowy zapisany w Markdownie. Otworzysz go i przeczytasz w każdym edytorze tekstu, np. w Notatniku w Windows albo w TextEdicie na Macu. Żeby zobaczyć formatowanie, otwórz go w aplikacji obsługującej Markdown, w edytorze kodu z podglądem (np. VS Code) albo w serwisie takim jak GitHub.

Czy Markdown działa tak samo w każdej aplikacji?

Nie do końca. Programy zgodne z CommonMark podobnie odczytują podstawową składnię, ale różnią się rozszerzeniami i sposobem wyświetlania w edytorze. Tabele, zadania i przekreślenie pochodzą z GFM, a wikilinki, wzory i diagramy wymagają dodatkowej obsługi.

Gwiazdki czy podkreślniki?

Jedne i drugie oznaczają kursywę lub pogrubienie, ale CommonMark inaczej traktuje je wewnątrz wyrazów: podkreślniki w plik_wersja_final nie tworzą wyróżnienia. Wybierz jeden styl i trzymaj się go, a nietypowe zapisy sprawdzaj w podglądzie.

Czy da się pisać w Markdownie na telefonie?

Tak. Markdown składa się ze zwykłych znaków, więc wpiszesz go na każdej klawiaturze telefonu. Wiele aplikacji do notatek pokazuje też nad klawiaturą pasek formatowania, który wstawia znaki za Ciebie. Grawis i tylda są zwykle na dodatkowej planszy symboli, a na niektórych klawiaturach grawis pojawia się po przytrzymaniu apostrofu.