Markdown jest jednym z tych narzędzi, które widzimy tak często, że przestajemy je zauważać. Otwieramy README na GitHubie - Markdown. Piszemy notatkę w Obsidianie - Markdown. Przygotowujemy dokumentację projektu, checklistę do pull requesta, komentarz w issue, opis zadania, plan pracy dla agenta AI - bardzo często znowu Markdown. Nawet jeśli aplikacja pokazuje nam ładny edytor, pod spodem nierzadko żyje prosty tekst z kilkoma znakami, które nadają mu strukturę.

Na pierwszy rzut oka to tylko wygodniejszy sposób pisania nagłówków, list i linków. Taki HTML dla ludzi, którym nie chce się pisać HTML-a. Ale im dłużej pracuję z dokumentacją, kodem i narzędziami opartymi o duże modele językowe, tym większe mam wrażenie, że sprawa jest bardziej złożona i ciekawa.

Markdown nie jest już tylko formatem tekstu. Coraz częściej jest językiem przekazywania intencji. Takim, w którym człowiek opisuje cel, kontekst, ograniczenia i kryteria jakości, a maszyna próbuje zamienić to na działanie.

Czy to oznacza, że Markdown stał się językiem programowania? Nie w klasycznym sensie. Ale być może zaczyna zajmować miejsce jeszcze wyżej: nad językami wysokiego poziomu, jako warstwa opisu pracy dla systemów, które same potrafią generować kod, uruchamiać narzędzia i podejmować decyzje w ramach zadania.

Skąd wziął się Markdown?

Markdown został opublikowany w 2004 roku przez Johna Grubera. Przy projekcie składni pomagał Aaron Swartz. Pomysł był prosty: stworzyć format, w którym da się pisać tekst czytelny dla człowieka, a potem zamienić go na poprawny HTML.

To ważne, bo w tamtym czasie Internet był już pełen treści, ale pisanie ich w HTML-u było dość niewygodne. Krótki akapit z linkiem wyglądał mniej więcej tak:

<p>
  Przeczytaj dokumentację na
  <a href="https://example.com">stronie projektu</a>.
</p>

To oczywiście działa. Problem polega na tym, że w prostym tekście znaczniki zaczynają konkurować z treścią. Człowiek chciał napisać zdanie, a musiał myśleć o tagach, atrybutach, nawiasach i zamykaniu elementów. Ba, zagnieżdżaniu ich względem siebie.

W Markdownie ten sam przykład jest bliższy naturalnemu językowi:

Przeczytaj dokumentację na [stronie projektu](https://example.com).

Różnica nie polega tylko na liczbie znaków. Chodzi o to, że tekst nadal wygląda jak tekst. Nawet bez renderowania wiemy, co jest linkiem, co jest nagłówkiem, co jest listą, a co fragmentem kodu.

Gruber pisał, że głównym celem składni Markdowna była czytelność. Dokument miał nadawać się do publikacji jako zwykły tekst, bez wrażenia, że ktoś rozsypał po nim techniczne znaczniki. To założenie okazało się ważniejsze niż mogło wyglądać w 2004 roku.

Format, który nie próbuje być zbyt mądry

Markdown wygrał w wielu miejscach właśnie dlatego, że nie próbuje robić wszystkiego. Nie ma rozbudowanego systemu stylów. Nie próbuje zastąpić edytora tekstu. Nie wymusza jednego środowiska pracy. Nie potrzebuje specjalnego programu, żeby dało się go przeczytać. W najgorszym przypadku otwieramy plik .md w zwykłym edytorze i nadal rozumiemy większość treści.

To jest nudna cecha, ale w praktyce bardzo cenna. Plik Worda bez Worda bywa problemem. Dokument w zamkniętym narzędziu jest zależny od tego narzędzia. Markdown jest zwykłym tekstem. Można go trzymać w Gicie, porównywać w diffie, przeszukiwać, generować, parsować, kopiować między systemami i archiwizować przez lata.

W pracy programisty takie szczegóły mają znaczenie. Dokumentacja nie żyje w idealnym świecie. Jest czytana w przeglądarce, w terminalu, w edytorze kodu, w pull requeście, w systemie wiki, czasem w surowym pliku. Markdown dobrze znosi te "przeprowadzki".

W dużym skrócie: Markdown jest wystarczająco strukturalny dla maszyn i wystarczająco naturalny dla ludzi.

Markdown jako język codziennej pracy programisty

Jeśli spojrzymy na współczesny projekt programistyczny, Markdown pojawia się niemal wszędzie.

W README.md opisujemy, czym jest projekt, jak go uruchomić i jakie ma wymagania. W CHANGELOG.md zapisujemy zmiany między wersjami. W dokumentacji architektonicznej wyjaśniamy decyzje, których nie widać bezpośrednio w kodzie. W issue i pull requestach opisujemy kontekst, akceptację, ryzyka i rzeczy do sprawdzenia.

Weźmy prosty przykład opisu zadania:

## Cel

Dodać walidację adresu e-mail w formularzu zapisu.

## Kryteria akceptacji

- Użytkownik widzi komunikat błędu po wpisaniu niepoprawnego adresu.
- Formularz nie wysyła danych, jeśli adres jest niepoprawny.
- Test obejmuje poprawny i niepoprawny adres.

To nie jest kod. A jednak taki opis realnie steruje pracą zespołu. Ustala zakres, kolejność myślenia i definicję sukcesu. Co więcej, jest łatwy do przetworzenia przez narzędzia. System może znaleźć sekcję "Kryteria akceptacji", agent może zamienić ją na checklistę, a człowiek może szybko ocenić, czy zadanie jest dobrze opisane.

Markdown zaczął więc pełnić funkcję, której nie da się sprowadzić do formatowania. Stał się prostym sposobem zapisu struktury myślenia.

Od tekstu do intencji

Zwróćmy uwagę na jeszcze jedną rzecz. Markdown nie mówi tylko: "ten tekst ma być większy", "ten fragment ma być pogrubiony", "tutaj jest lista". On bardzo często mówi:

• to jest cel,
• to jest kontekst,
• to są ograniczenia,
• to są kroki,
• to jest przykład,
• to jest kod,
• to jest wynik, którego oczekujemy.

Oczywiście sam Markdown nie rozumie tych pojęć. Parser widzi nagłówki, listy i bloki kodu. Ale dla człowieka, zespołu i coraz częściej dla modelu językowego ta prosta struktura jest wystarczająca, żeby odtworzyć sens dokumentu.

Dlatego Markdown tak dobrze przyjął się w pracy z agentami AI. Agent potrzebuje kontekstu, instrukcji, przykładów, ograniczeń i kryteriów jakości. Markdown pozwala zapisać to bez projektowania osobnego formatu danych.

Możemy napisać:

## Zadanie

Przenieś walidację formularza do osobnej funkcji.

## Ograniczenia

- Nie zmieniaj publicznego API komponentu.
- Nie ruszaj stylów.
- Dodaj test dla pustego pola.

## Definicja gotowości

- Testy formularza przechodzą.
- Kod jest czytelniejszy niż przed zmianą.

Dla klasycznego kompilatora to zwykły tekst. Dla agenta to już całkiem precyzyjna instrukcja pracy. Ma cel, granice, zakres i kryteria weryfikacji. Nie opisujemy pętli, warunków ani struktur danych. Opisujemy intencję.

Czy Markdown jest językiem programowania?

Tutaj warto zachować ostrożność, bo łatwo odpłynąć w zbyt mocną tezę. Markdown nie jest językiem programowania w tradycyjnym sensie. Sam z siebie niczego nie wykonuje. Nie ma typów, funkcji, wyjątków, kontroli przepływu ani standardowej biblioteki. Sam z siebie nie policzy podatku, nie pobierze danych z API i nie zapisze rekordu w bazie.

Ale pytanie, które mnie interesuje, brzmi inaczej: czy w pracy z systemami AI Markdown zaczyna pełnić funkcję podobną do języka sterującego?

W klasycznym programowaniu języki wysokiego poziomu opisują procedurę. Możemy pisać w Pythonie, JavaScripcie, PHP, Ruby czy Go, ale nadal mówimy komputerowi, jak ma przejść od danych wejściowych do wyniku. Abstrakcja jest wyższa niż w assemblerze, ale logika wykonania nadal leży po naszej stronie.

Programiści broniący wyższości pracy z kodem często zapominają, że sami też nie kontrolują bezpośrednio tego, jak ich instrukcje zostaną przetłumaczone na język maszynowy.

W pracy z agentem coraz częściej robimy coś innego. Nie opisujemy dokładnie, jak rozwiązać problem. Opisujemy, co chcemy osiągnąć, w jakim kontekście, z jakimi ograniczeniami i po czym poznamy, że wynik jest dobry.

To jest poziom abstrakcji powyżej typowego języka wysokiego poziomu. Nie dlatego, że Markdown jest "lepszy" od języków programowania. To byłoby bez sensu. Markdown nie zastąpi języka, w którym budujemy aplikację. Ale może stać się językiem, w którym opisujemy pracę wykonywaną później przez system zdolny do używania tych języków.

Innymi słowy: język wysokiego poziomu mówi maszynie, jak wykonać program. Markdown w pracy agentowej coraz częściej mówi maszynie, jaki program lub zmianę ma dopiero przygotować.

Dlaczego akurat Markdown?

Można zapytać: dlaczego nie JSON, YAML albo XML? Przecież wszystkie te formaty nadają się do przekazywania ustrukturyzowanych danych.

Odpowiedź jest prosta: bo Markdown jest przyjaźniejszy dla człowieka. JSON świetnie sprawdza się jako format danych. YAML bywa wygodny w konfiguracji. XML nadal ma swoje miejsca w integracjach i dokumentach. Ale gdy chcemy połączyć opis, kontekst, przykłady, kod i decyzje projektowe to Markdown jest naturalniejszy.

Porównajmy dwa zapisy tej samej intencji.

{
  "task": "Dodaj testy dla formularza",
  "constraints": [
    "Nie zmieniaj publicznego API",
    "Nie ruszaj stylów"
  ],
  "done": [
    "Test obejmuje poprawne dane",
    "Test obejmuje błędny adres e-mail"
  ]
}

To jest precyzyjne, ale mało wygodne jako notatka dla człowieka. Teraz Markdown:

## Zadanie

Dodaj testy dla formularza.

## Ograniczenia

- Nie zmieniaj publicznego API.
- Nie ruszaj stylów.

## Gotowe, gdy

- Test obejmuje poprawne dane.
- Test obejmuje błędny adres e-mail.

Druga wersja jest mniej formalna, a jednocześnie lepiej przyswajalna przez "interfejs białkowy". Możemy dopisać akapit wyjaśnienia, wkleić fragment kodu, dodać link do pull requesta, zacytować decyzję z rozmowy i nadal nie niszczymy czytelności dokumentu.

To jest dokładnie ten rodzaj elastyczności, którego potrzebujemy w pracy z ludźmi i agentami. Zbyt sztywny format wymaga narzędzi. Zbyt luźny tekst gubi strukturę. Markdown jest pośrodku.

Rozszerzenia, czyli cena popularności

Oczywiście historia Markdowna nie jest idealna. Prostota miała swoją cenę.

Oryginalny Markdown był opisany raczej jako praktyczna składnia i narzędzie niż bardzo formalna specyfikacja. Gdy format zaczął być używany w wielu miejscach, pojawiły się różnice między implementacjami. Jedna wersja obsługiwała tabele, inna przypisy, jeszcze inna listy z checkboxami. Czasem ten sam dokument renderował się inaczej w dwóch narzędziach.

Stąd między innymi standard CommonMark, czyli próba uściślenia składni i przygotowania zestawu testów. Stąd też GitHub Flavored Markdown, który rozwinął Markdowna o rzeczy potrzebne w codziennej pracy na GitHubie, takie jak tabele, przekreślenia czy listy zadań.

Do tego doszły kolejne światy:

• MDX pozwala łączyć Markdowna z komponentami JSX,
• Pandoc potrafi konwertować dokumenty między wieloma formatami,
• Marp używa Markdowna do tworzenia prezentacji,
• Mermaid pozwala zapisywać diagramy tekstem,
• wiele narzędzi dodaje matematykę, przypisy, metadane i własne rozszerzenia.

Czy to nadal ten sam Markdown? W większości przypadków tak, ale trzeba pamiętać o kontekście. Markdown z GitHuba, Markdown w Obsidianie, Markdown w statycznym generatorze stron i Markdown w systemie dokumentacji mogą różnić się szczegółami.

W praktyce warto ustalić jedno pytanie: dla jakiego silnika renderującego piszemy? Jeśli tekst ma być czytany tylko przez ludzi, różnice są mniej bolesne. Jeśli ma zasilać pipeline publikacji, dokumentację produktu albo agentowy workflow, szczegóły składni zaczynają mieć znaczenie.

Co może pójść nie tak?

Markdown jest prosty, ale nie magiczny. Pierwszy problem to fałszywe poczucie standaryzacji. Plik .md wygląda niewinnie, więc zakładamy, że wszędzie zadziała tak samo. Potem okazuje się, że tabele renderują się inaczej, HTML jest sanitizowany, checkboxy nie działają, a bloki kodu wymagają innego oznaczenia języka.

Drugi problem to mieszanie dokumentu z aplikacją. MDX i podobne narzędzia są bardzo wygodne, ale gdy w tekście zaczyna pojawiać się dużo komponentów, importów i logiki, tracimy część pierwotnej zalety Markdowna. Surowy plik przestaje być łatwy do czytania.

Trzeci problem dotyczy pracy z AI. Markdown jest świetny do opisywania zadań, ale nie daje gwarancji wykonania. Agent może źle zinterpretować sekcję, pominąć ograniczenie albo potraktować przykład jako regułę. Struktura pomaga, ale nie zastępuje walidacji, testów i przeglądu.

Warto więc nie mylić czytelnego opisu z formalną specyfikacją. Markdown może być bardzo dobrym interfejsem, ale nadal potrzebujemy mechanizmów sprawdzających, czy wynik jest poprawny.

Kiedy Markdown ma największy sens?

Markdown sprawdza się najlepiej tam, gdzie treść musi być jednocześnie czytelna, wersjonowalna i możliwa do przetwarzania przez narzędzia.

Jeśli piszemy dokumentację dla programistów, trudno o bardziej naturalny wybór. Możemy trzymać przykłady kodu obok wyjaśnień. Możemy recenzować dokumentację w pull requestach. Możemy generować z niej stronę, PDF albo fragmenty treści w aplikacji jak tooltipy, komunikaty błędów czy elementy changeloga.

Jeśli pracujemy z agentami AI, Markdown jest dobrym formatem do opisu zadań, planów, decyzji i raportów. Nagłówki porządkują kontekst, listy upraszczają wymagania, bloki kodu oddzielają instrukcje od przykładów, a cytaty pomagają zachować źródłowy fragment rozmowy lub dokumentu.

Jeśli jednak potrzebujemy twardego kontraktu między systemami, Markdown może być za miękki. API lepiej opisać schematem. Dane lepiej przesłać JSON-em. Złożoną konfigurację lepiej trzymać w formacie, który da się walidować. Markdown jest świetny jako warstwa komunikacji, ale nie zawsze jako źródło danych dla systemu.

Podsumowanie

Markdown przetrwał, bo jest skromny. Nie wymaga od nas dużej inwestycji, nie zamyka w jednym narzędziu i nie próbuje udawać kompletnego środowiska pracy. Jest prostym tekstem, który potrafi unieść zaskakująco dużo znaczenia.

Zaczynał jako wygodniejszy sposób pisania treści do Internetu. Potem stał się domyślnym formatem dokumentacji technicznej. Dzisiaj coraz częściej jest także formatem rozmowy z maszynami: w promptach, instrukcjach, planach pracy, raportach i definicjach gotowości.

Nie powiedziałbym, że Markdown zastępuje języki programowania. To byłaby zła teza. Powiedziałbym raczej, że pojawił się nad nimi jako prosty język intencji. Człowiek opisuje w nim, co ma się wydarzyć. Agent, narzędzie albo zespół próbują zamienić ten opis na konkretną zmianę.

I może właśnie dlatego Markdown jest tak ciekawy. Nie wygrał dlatego, że był najbardziej formalny. Wygrał dlatego, że był wystarczająco formalny, aby pomóc maszynom, i wystarczająco naturalny, abyśmy nadal chcieli w nim pisać.