Blog JSystems - uwalniamy wiedzę!
Blog JSystems - uwalniamy wiedzę!
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.
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ą.
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.
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.
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.
Najczęstsze wyróżnienia tekstu w jednej linijce:
**tak** albo dwoma podkreśleniami __tak__.*tak* lub jedno podkreślenie _tak_.***tak***.~~tak~~ (element GitHub Flavored Markdown).`kod`, przydatny do nazw plików, poleceń i fragmentów kodu wplecionych w zdanie.
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..
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.
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ć.
- [x] daje pole zaznaczone, - [ ] puste.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.
Obraz zapisujesz prawie jak link, tylko z wykrzyknikiem ! na początku: . 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ć.
!. Tekst w nawiasie kwadratowym to opis alternatywny.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.
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.
>. Można go zagnieżdżać i dodawać do niego formatowanie.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.
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.
Markdown nie ma jednej, sztywnej definicji — przez lata powstało kilka odmian. Dwie, które warto znać:
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.
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 | ```język ... ``` |
Wielowierszowy kod z kolorowaniem |
| Lista punktowana | - pozycja |
Punkty z kropkami |
| Lista numerowana | 1. pozycja |
Punkty z numeracją |
| Lista zadań | - [ ] / - [x] |
Pola do zaznaczenia (GFM) |
| Link | [opis](adres) |
Klikalny odnośnik |
| Obraz |  |
Wstawiony obraz |
| Cytat | > tekst |
Cytat blokowy |
| Tabela | | a | b | |
Tabela (GFM) |
| Linia pozioma | --- |
Pozioma kreska |
| Znak ucieczki | \* |
Dosłowny znak * |
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 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.
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 termin gwarantowany.
Komentarze (0)
Brak komentarzy...