Andrzej Klusiewicz

Posted on Sep 12

Markdown od podstaw - kompletna sciaga skladni ze wszystkimi elementami

#markdown #webdev #writing #tutorial

Markdown wyglada na prosty jezyk znacznikow, dopoki nie trzeba w nim zrobic tabeli, zagniezdzonej listy albo bloku kodu z podswietlaniem skladni. Ten tekst zbiera cala skladnie Markdown w jednym miejscu, z przykladami.

Markdown od podstaw — wszystkie najważniejsze elementy składni.

Markdown to lekki język znaczników, którym formatujesz tekst za pomocą zwykłych znaków: nagłówek oznaczasz znakiem #, pogrubienie gwiazdkami, listę myślnikami. Plik zostaje czytelny tak, jak go napisałeś, a narzędzia takie jak GitHub, edytory kodu czy generatory dokumentacji zamieniają go w ładnie sformatowany dokument. W tym artykule przejdziesz po kolei przez wszystkie najważniejsze elementy składni.

Żeby nie była to sucha teoria, każdy element pokazujemy w dwóch panelach obok siebie: po lewej widzisz źródło (to, co wpisujesz), a po prawej gotowy wynik (to, co zobaczy czytelnik po przetworzeniu). Wszystkie podglądy w artykule to prawdziwy render wygenerowany standardowym parserem Markdown, a nie ręcznie narysowane przykłady.

Z tego artykułu dowiesz się

czym jest Markdown i czym różni się od HTML,
jak robić nagłówki, akapity i twarde łamanie linii,
jak pogrubiać, pochylać i przekreślać tekst oraz wstawiać kod w linii,
jak budować listy punktowane, numerowane, zagnieżdżone i listy zadań,
jak wstawiać linki i obrazy,
jak tworzyć bloki kodu z kolorowaniem składni,
jak robić cytaty i tabele,
jak działa znak ucieczki i czym jest GitHub Flavored Markdown,
na koniec dostaniesz ściągę z całą składnią w jednym miejscu.

Czym jest Markdown

Markdown to sposób zapisu tekstu, w którym formatowanie wyrażasz prostymi znakami zamiast klikania przycisków czy pisania rozwlekłych tagów. Stworzył go w 2004 roku John Gruber z jednym celem: żeby tekst był czytelny zarówno w surowej postaci, jak i po przetworzeniu. Dlatego nawet bez żadnego narzędzia plik Markdown da się spokojnie przeczytać.

Spotkasz go niemal wszędzie w świecie IT: pliki README.md w repozytoriach na GitHubie i GitLabie, dokumentacja projektów, opisy zgłoszeń (ang. issues) i komentarze, notatki w aplikacjach typu Obsidian czy Notion, a także pliki kontekstu dla narzędzi AI (np. CLAUDE.md). Znajomość Markdown to dziś podstawowa umiejętność każdego programisty i osoby pracującej z dokumentacją techniczną.

Markdown a HTML

Ten sam efekt można uzyskać w HTML (języku, którym opisuje się strony internetowe), ale jest on dużo bardziej rozwlekły. Nagłówek w HTML to <h1>Tytuł</h1>, a w Markdownie po prostu # Tytuł. Markdown nie zastępuje HTML — pod spodem i tak zamienia się na HTML — ale pozwala zapisać typowe formatowanie znacznie szybciej i czytelniej. Gdy potrzebujesz czegoś, czego Markdown nie obsługuje, w większości parserów możesz wstawić surowy HTML wprost w tekst.

Jak czytać przykłady poniżej: lewy, ciemny panel to źródło Markdown — dokładnie to, co wpisujesz w pliku. Prawy, jasny panel to wynik — tak zobaczy go czytelnik po przetworzeniu przez parser.

Nagłówki

Nagłówki tworzysz, stawiając na początku wiersza od jednego do sześciu znaków #, po których następuje spacja. Jeden # to nagłówek najwyższego poziomu (odpowiednik <h1>), sześć to najniższy. W jednym dokumencie powinien być tylko jeden nagłówek pierwszego poziomu — to tytuł. Istnieje też starszy zapis podkreśleniem (znakami = i - pod tekstem), który działa tylko dla dwóch najwyższych poziomów.

Nagłówki: od jednego do czterech znaków # po lewej, gotowy efekt po prawej. Na dole alternatywny zapis podkreśleniem.

Akapity i łamanie linii

Akapit to po prostu tekst oddzielony od reszty pustym wierszem. Co ważne, pojedyncze złamanie linii (zwykły Enter) parser standardowo traktuje jako spację i skleja wiersze w jeden akapit. Żeby wymusić twarde przejście do nowej linii bez zaczynania nowego akapitu, kończysz wiersz dwiema spacjami. Nowy akapit zaczynasz, zostawiając między blokami pusty wiersz.

Pusty wiersz rozdziela akapity, a dwie spacje na końcu wiersza wymuszają twarde złamanie linii.

Pogrubienie, kursywa, przekreślenie i kod w linii

Najczęstsze wyróżnienia tekstu w jednej linijce:

Pogrubienie — otaczasz tekst dwiema gwiazdkami **tak** albo dwoma podkreśleniami __tak__.
Kursywa (pochylenie) — jedna gwiazdka *tak* lub jedno podkreślenie _tak_.
Pogrubienie z kursywą — trzy gwiazdki ***tak***.
Przekreślenie — dwie tyldy ~~tak~~ (element GitHub Flavored Markdown).
Kod w linii — fragment otoczony pojedynczym znakiem grawisu `kod`, przydatny do nazw plików, poleceń i fragmentów kodu wplecionych w zdanie.

Wyróżnienia tekstu: pogrubienie, kursywa, połączenie obu, przekreślenie i kod w linii.

Listy

Listę punktowaną (nieuporządkowaną) zaczynasz każdą pozycję myślnikiem -, gwiazdką * lub plusem + i spacją. Listę numerowaną tworzysz, pisząc liczbę, kropkę i spację. Co ciekawe, w liście numerowanej nie musisz pilnować kolejnych numerów — parser i tak ponumeruje pozycje od góry, więc spokojnie możesz wszędzie wpisać 1..

Lista punktowana (myślniki) i lista numerowana (liczba z kropką).

Listy zagnieżdżone

Listę można zagnieżdżać — czyli wkładać jedną w drugą. Element podrzędny tworzysz, robiąc przed nim wcięcie (zwykle dwie spacje na każdy poziom). W ten sposób budujesz strukturę drzewa, a poziomy możesz dowolnie mieszać: pod punktem listy punktowanej może być lista numerowana i odwrotnie.

Wcięcie tworzy poziom podrzędny. Poziomy można mieszać — punktory z numeracją.

Listy zadań

Lista zadań (ang. task list) to specjalna lista z polami do zaznaczenia. Każdą pozycję zaczynasz od - [ ] (puste pole) lub - [x] (zaznaczone). To element GitHub Flavored Markdown, świetny do list rzeczy do zrobienia w opisach zgłoszeń i w plikach README — na GitHubie takie pola da się nawet klikać.

Lista zadań: - [x] daje pole zaznaczone, - [ ] puste.

Linki

Najprostszy link to tekst w nawiasie kwadratowym i adres w okrągłym: [opis](adres). Możesz dodać tytuł pokazywany po najechaniu kursorem, wpisując go w cudzysłowie po adresie. Sam adres otoczony znakami < i > staje się klikalnym linkiem bez opisu. Jest też zapis referencyjny: w tekście używasz etykiety, a właściwy adres definiujesz w osobnym miejscu — porządkuje to długie dokumenty z wieloma odnośnikami.

Cztery sposoby na link: zwykły, z tytułem po najechaniu, automatyczny oraz referencyjny.

Obrazy

Obraz zapisujesz prawie jak link, tylko z wykrzyknikiem ! na początku: ![opis](adres-obrazka). Tekst w nawiasie kwadratowym to opis alternatywny (atrybut alt) — pokazuje się, gdy obraz się nie wczyta, i czytają go czytniki ekranu, więc warto go zawsze uzupełniać.

Obraz to składnia linku poprzedzona znakiem !. Tekst w nawiasie kwadratowym to opis alternatywny.

Bloki kodu

Dłuższy fragment kodu umieszczasz w bloku: otaczasz go trzema znakami grawisu (

```

) w osobnych wierszach. Zaraz po otwierających grawisach możesz podać nazwę języka, np.

```python

— wtedy narzędzie pokoloruje składnię. To dużo czytelniejsze niż wcinanie kodu spacjami, które też jest dozwolone, ale nie pozwala wskazać języka.

Blok kodu między trzema grawisami. Nazwa języka po otwierających grawisach włącza kolorowanie składni.

Cytaty

Cytat blokowy tworzysz, stawiając na początku wiersza znak >. Cytaty można zagnieżdżać (dwa znaki >> dają cytat w cytacie) i wstawiać do nich inne formatowanie — pogrubienia, listy czy kod. Często używa się ich do wyróżnienia uwag, ostrzeżeń albo przytoczenia czyjejś wypowiedzi.

Cytat zaczyna się od znaku >. Można go zagnieżdżać i dodawać do niego formatowanie.

Tabele

Tabele należą do GitHub Flavored Markdown. Kolumny rozdzielasz znakiem pionowej kreski |, a wiersz nagłówków oddzielasz od danych wierszem z myślnikami. Dwukropki w tym wierszu rozdzielającym sterują wyrównaniem kolumny: :--- do lewej, :--: do środka, ---: do prawej. W źródle kolumny nie muszą się idealnie zgadzać szerokością — parser i tak je wyrówna.

Tabela: pionowe kreski rozdzielają kolumny, a dwukropki w wierszu rozdzielającym ustawiają wyrównanie.

Linia pozioma i znak ucieczki

Poziomą linię oddzielającą sekcje wstawisz, pisząc w osobnym wierszu trzy myślniki --- (albo trzy gwiazdki lub trzy podkreślenia). Czasem chcesz pokazać znak, który normalnie coś znaczy w składni — na przykład gwiazdkę albo #. Wtedy poprzedzasz go lewym ukośnikiem \ (znakiem ucieczki), a parser potraktuje go jak zwykły tekst.

Trzy myślniki dają poziomą linię. Lewy ukośnik przed znakiem wyłącza jego znaczenie w składni.

Warianty Markdown: CommonMark i GFM

Markdown nie ma jednej, sztywnej definicji — przez lata powstało kilka odmian. Dwie, które warto znać:

CommonMark — uporządkowany, precyzyjny standard podstawowej składni. Obejmuje wszystko z tego artykułu poza tabelami, listami zadań i przekreśleniem.
GitHub Flavored Markdown (GFM) — rozszerza CommonMark o praktyczne dodatki: tabele, listy zadań, przekreślenie oraz automatyczną zamianę adresów na linki. To dziś najpopularniejsza odmiana, obsługiwana przez większość platform i edytorów.

W praktyce różnice rzadko przeszkadzają — podstawy działają wszędzie tak samo. Jeśli korzystasz z elementu GFM (np. tabeli) w narzędziu, które go nie wspiera, zobaczysz po prostu surowy zapis zamiast sformatowanej tabeli.

Ściąga — cała składnia w jednym miejscu

Krótkie podsumowanie do trzymania pod ręką:

Element	Zapis w Markdown	Efekt
Nagłówki	`# H1` ... `###### H6`	Tytuły poziomów 1-6
Pogrubienie	`tekst`	Tekst pogrubiony
Kursywa	`tekst`	Tekst pochylony
Przekreślenie	`~~tekst~~`	Tekst przekreślony (GFM)
Kod w linii	`kod`	Wyróżniony fragment kodu
Blok kodu

Najlepszy sposób, żeby to zapamiętać, to napisać własny plik README.md — choćby krótki opis projektu z nagłówkiem, listą i blokiem kodu. Po kilku takich plikach składnia wchodzi w nawyk i piszesz ją bez zaglądania do ściągi.

Markdown w pracy z narzędziami AI

Markdown ma dziś jeszcze jedno ważne zastosowanie: to język, w którym opisujemy kontekst i instrukcje dla narzędzi sztucznej inteligencji wspierających programistów. Claude Code — agentowe narzędzie AI działające w terminalu — czyta plik CLAUDE.md, w którym w Markdownie opisujesz zasady projektu, konwencje i to, jak ma się zachowywać. Czytelne nagłówki, listy i bloki kodu w tym pliku przekładają się wprost na to, jak dobrze narzędzie zrozumie Twój projekt. Te same podstawy, których właśnie się nauczyłeś, są więc fundamentem skutecznej pracy z AI.

Chcesz pójść dalej niż formatowanie tekstu?

Markdown to pierwszy krok. Jeśli chcesz wykorzystać go tam, gdzie naprawdę przyspiesza pracę — w opisywaniu projektów i kierowaniu agentem AI w codziennym programowaniu — poznaj Claude Code z doświadczonym trenerem. Kurs ma terminy gwarantowane.

Szkolenie Claude Code

To szkolenie może być dofinansowane dla Ciebie z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5

DEV Community