Dostępnik o Markdown

Markdown ma 20 lat. Powstał jako lekka alternatywa dla HTML – coś, co da się czytać i pisać w zwykłym notatniku, a jednocześnie zamienić na ładną stronę internetową. Dziś jest wszędzie: GitHub, Obsidian, Notion, Slack, Discord, WordPress (block editor), Reddit, SMS-y (działają italic na iOS).

Ale dopiero w połączeniu z AI Markdown pokazuje swoją prawdziwą siłę. I nie chodzi o kolejny poradnik “jak formatować tekst”. Chodzi o coś głębszego: Markdown to pomost między tym, jak myślimy my, jak myślą modele językowe i jak działa sieć.

Ten tekst jest o tym, dlaczego to ma znaczenie – szczególnie dla dostępności. A jeżeli kręcisz teraz głową, że wcale nie znasz Markdown, to coś Ci podpowiem. Kiedy korzystasz z jakiegoś chata AI, na przykład Gemini, Chat GPT i klikniesz na przycisk skopiowania treści, najczęściej lub wręcz zawsze, w schowku znajduje się właśnie Markdown. Te krzyżyki (#), listy zaczynające się od gwiazdek i tabele zbudowane z z kresek pionowych i poziomych, to właśnie jest Markdown.

Moim głównym celem jest przekonanie kogo się da, że publikacje o dostępności – ale też każda inna treść – powinny być publikowane w Markdown, obok tradycyjnego PDF. Nie zamiast, tylko obok.

PDF jest formatem zamkniętym. Dla AI to czarna skrzynka – model musi najpierw wyciągnąć tekst przez OCR, odtworzyć strukturę, zgadnąć hierarchię nagłówków. Markdown jest od razu czytelny: człowiek go rozumie, AI go rozumie, a Git widzi każdą zmianę.

Rozmiar też ma znaczenie. Ten tekst w Markdown waży ok. 15 KB. Jako PDF z podstawowym formatowaniem – 10 razy więcej. Jako DOCX z nagłówkami i stylami – jeszcze więcej. W Markdown to czysty tekst, który otworzysz w edytorze z lat 90., prześlesz w sekundę i przetworzysz przez dowolny model językowy bez żadnej wstępnej obróbki.

Weźmy prosty nagłówek. W HTML:

<h1 class=”main-title text-3xl font-bold mb-4” data-section=”intro” id=”tytul-strony”>
Witaj w dostępności
</h1>

W Markdown:

# Witaj w dostępności

Model językowy dostając Markdown nie musi przebijać się przez class, data-*, id, zagnieżdżenia i atrybuty. Semantyka jest w strukturze, nie w atrybutach. Nagłówek z # to dla AI jasny sygnał: “to jest tytuł sekcji, a nie przypadkowy pogrubiony tekst”.

Badania nad wydajnością LLM na różnych formatach wejściowych (np. porównania Retrieval-Augmented Generation) konsekwentnie pokazują, że Markdown przegrywa tylko z czystym tekstem pod względem precyzji ekstrakcji informacji – ale wygrywa z HTML, JSON i DOCX, bo dostarcza strukturę bez zbędnego balastu. A semantyka treści bardzo wspomaga rozumienie treści przez AI. Wie, gdzie zaczyna się i kończy jakaś sekcja, ile elementów ma lista itp.

HTML miesza warstwy:

<p style=”color: red; font-size: 14px; line-height: 1.5;”>
<strong>Uwaga!</strong> To jest ważne.
</p>

Markdown rozdziela:

**Uwaga!** To jest ważne.

Dla AI to kluczowe: model nie musi zgadywać, czy color: red ma znaczenie semantyczne, czy to tylko styl. W Markdown to, co wygląda jak struktura, jest strukturą. Lista z - to lista. Cytat z > to cytat. Link z [tekst](url) to link.

Gdy prosisz AI o napisanie czegoś w HTML, dostajesz często:

· Brakujące zamykające tagi

· Niespójne klasy CSS

· Zagnieżdżenia, które nie mają sensu

· <div> zamiast <nav>, <span> zamiast <button>

W Markdown tych problemów nie ma. Format jest na tyle prosty, że model rzadko popełnia błędy składniowe. A jeśli popełni – poprawka to sekunda, a nie debugowanie zagnieżdżonych tagów.

To ma konkretny wymiar dostępnościowy: gdy AI generuje artykuł w Markdown, prawdopodobieństwo, że nagłówki będą poprawnie zhierarchizowane (# → ## → ###) jest dużo wyższe niż w HTML. A hierarchia nagłówków to istotny element semantyki, a zatem także dostępności.

Markdown ma wbudowaną semantykę, która pokrywa się z WCAG:

Element MD

Znaczenie a11y

Odpowiednik WCAG

# Nagłówek

Określa hierarchię

1.3.1 Informacje i relacje

[tekst](url)

Link z widocznym tekstem

2.4.4 Cel łącza (w kontekście)


Wymusza tekst alternatywny

1.1.1 Treść nietekstowa

- lista

Struktura listy

1.3.1

> cytat

Cytat blokowy

1.3.1

kod

Wyróżnienie techniczne

1.3.1

Uwaga: to działa tylko wtedy, gdy autor używa tych elementów zgodnie z przeznaczeniem. # dla wszystkiego co pogrubione psuje hierarchię. Ale Markdown nie ułatwia robienia rzeczy źle, bo tak użyty znacznik… po prostu nie zadziała. W przeciwieństwie do edytorów WYSIWYG, gdzie zmiana rozmiaru czcionki jest łatwiejsza niż ustawienie prawidłowego nagłówka.

W HTML można wstawić <img src=”foto.jpg”> bez alt – przeglądarka i tak wyświetli. W Markdown składnia  wymusza zastanowienie się nad tekstem alternatywnym. Puste ![]() jest oczywistym sygnałem, że czegoś brakuje. To subtelna, ale skuteczna sugestia - popycha autora w dobrym kierunku.

Pomysł na ten tekst nie wziął się znikąd. Dominik Batorski – polski naukowiec i popularyzator otwartej nauki – postuluje, żeby artykuły naukowe były publikowane w Markdown, a nie tylko w PDF. Jego argumenty są proste: format powinien być otwarty, maszynowo czytelny i wersjonowalny. Dokładnie to samo dotyczy dostępności.

Równolegle Fundacja Kultury bez barier (FKBB) opracowała standardy dostępności dla multimediów – język migowy, audiodeskrypcja, napisy. To ważna i potrzebna robota. Ja sam przetworzyłem te materiały do Markdown, żeby zasilić lokalną bazę wiedzy o dostępności. Ale po co każdy ma to robić od nowa? Gdyby standardy FKBB były dostępne w Markdown jako format źródłowy – wystarczyłoby podlinkować, nie kopiować.

Markdown jako format publikacji rozwiązałby ten problem u źródła: strona z publikacją wygląda ładnie w przeglądarce, a obok leży plik .md do ściągnięcia. Gotowy dla AI, gotowy do indeksowania, gotowy do tłumaczenia.

Mając artykuł w Markdown, AI może:

· Wygenerować podsumowanie dla czytelników z zaburzeniami poznawczymi

· Przetłumaczyć na prosty język (plain language)

· Dodać brakujące alt do obrazków

· Sprawdzić hierarchię nagłówków i zaproponować poprawki

· Wygenerować nawigację wewnątrz dokumentu (spis treści)

Markdown w Git to:

· Historia zmian każdego zdania – kto, co, kiedy zmienił

· Code review na treści – możesz robić pull request do artykułu

· Automatyczne sprawdzanie dostępności przez CI (np. markdownlint + reguły a11y)

· AI może przejrzeć “diff” między wersjami i sprawdzić, czy nowa treść nie psuje dostępności

Ten sam plik .md:

· Działa w Obsidianie (twój mózg)

· Publikuje się na GitHubie (współpraca)

· Ładuje się w CMS-ie (WordPress ma parser MD)

· Przetwarza się przez AI (analityka, podsumowania)

· Czyta się w terminalu (cat, less)

· Konwertuje na HTML, PDF, EPUB, DOCX

· Możesz go używać w Dokumentach Google i Substack

Nie ma drugiego formatu, który łączyłby wszystkie te światy. To nie przypadek, że dokumentacja techniczna, repozytoria kodu, ta wiki i notatniki AI używają Markdown.

Podstawowy Markdown obsługuje nagłówki, listy, linki, obrazki, cytaty i kod. Tyle wystarcza do 80% dokumentacji. Gdy potrzebujesz więcej – wchodzą rozszerzenia.

Mermaid (

https://mermaid.js.org/

) to osobne narzędzie do rysowania diagramów za pomocą tekstu, które działa obok Markdown. Schemat blokowy, diagram sekwencji, wykres Gantta, diagram ERD, mapa myśli – wszystko w kilku linijkach kodu w bloku z etykietą mermaid. GitLab i GitHub renderują je natywnie, podobnie jak Obsidian i Notion. Diagram staje się częścią repozytorium, jest wersjonowany, widać różnice między wersjami w pull requeście. Dla dostępności to przełom: diagram zapisany jako tekst ma wbudowaną warstwę semantyczną. Osoby niewidome mogą czytać kod źródłowy, a autor może dodać opis alternatywny bez trzymania osobnego pliku. AI też rozumie kod Mermaid i potrafi go wygenerować z opisu słownego. Ja użyłem go do mapowania polskiego prawa o dostępności.

MMD to dialekt Markdown używany głównie w Obsidianie, który rozszerza składnię o wykresy Mermaid, osadzone notatki przez wikilinki ([[link]]), tagi, zadania do odhaczenia (- [ ]), właściwości w YAML frontmatter i wiele innych. Różni się od czystego Markdown tym, że nie jest przenośny – działa tylko w Obsidianie i kilku innych aplikacjach. To cena za funkcje, które wykraczają poza standard GFM (GitHub Flavored Markdown). MMD pokazuje, jak daleko można przesunąć granice Markdown, gdy kontrolujesz cały ekosystem.

MDX (

https://mdxjs.com/

) idzie o krok dalej: łączy Markdown z JSX, czyli składnikami interaktywnymi z Reacta. W jednym pliku masz tekst pisany naturalnie, a obok niego działający komponent – formularz, kalkulator, interaktywny wykres, osadzony odtwarzacz. Używam MDX w jednym z projektów i to zmienia sposób myślenia o dokumentacji: przestajesz segregować treść od kodu. Przykładowo, opisujesz regułę dostępności WCAG i od razu obok wstawiasz interaktywny przykład, który czytelnik może przetestować. Kod źródłowy i opis są w jednym pliku, wersjonowane razem, nie rozjeżdżają się w czasie. MDX wymaga jednak środowiska uruchomieniowego – nie działa w zwykłym notatniku jak czysty Markdown. To kompromis: zyskujesz interaktywność, tracisz uniwersalność. Ale dla projektów, gdzie dokumentacja ma być żywym narzędziem, to idealne rozwiązanie.

Markdown nie jest jedynym lekkim językiem znaczników. Warto znać alternatywy:

• reStructuredText (RST) (https://docutils.sourceforge.io/rst.html) – używany głównie w ekosystemie Pythona (Sphinx, Read the Docs), rozbudowany system ról i dyrektyw. Bardziej ekspresyjny niż Markdown, ale też bardziej skomplikowany. Idealny do dokumentacji technicznej, gdzie potrzebujesz automatycznych indeksów i krzyżowych referencji.

• AsciiDoc (

https://asciidoc.org/

• ) – jeszcze potężniejszy format, używany w dokumentacji Red Hata i projektu Antora. Obsługuje admonicje, bloki źródłowe z etykietami, tabele z formatowaniem, wbudowane makra. Asciidoctor konwertuje do HTML, PDF, DocBook. Używałem go do generowania raportów, bo miał funkcję ‘include’, co pozwalało na dynamiczne dołączanie treści z innych plików.

• Textile, Creole, MediaWiki markup – starsze formaty, każdy z własnym dialektem. Nie przetrwały próby czasu tak dobrze jak Markdown.

Każdy z tych formatów ma swoją niszę. Ale żaden nie osiągnął poziomu adopcji Markdown – ani w społeczności deweloperskiej, ani w AI, ani w systemach CMS.

Markdown sprawdza się w praktyce w trzech obszarach, które dotyczą mnie bezpośrednio:

Od wielu lat piszę w Markdown. Końcowy dokument – czy to raport, artykuł czy notatka – konwertuję dopiero na ostatnim etapie. Dzięki temu mam czyste źródło, które działa w każdym narzędziu.

Pandoc to szwajcarski scyzoryk konwersji dokumentów. Umie czytać i pisać praktycznie wszystko: Markdown, HTML, LaTeX, DOCX, EPUB, PDF, RST, AsciiDoc i dziesiątki innych formatów.:

Pandoc rozumie rozszerzoną składnię Markdown: tabele, przypisy dolne, metadane YAML. Dzięki temu możesz pisać w Markdown, a produkować cokolwiek potrzebujesz. To właśnie ta konwersja sprawia, że Markdown jest praktycznym formatem źródłowym – od niego zaczynasz, do niego wracasz, a reszta to tylko eksport.

Wiele systemów do generowania stron statycznych opiera się na Markdown. Hugo (Go) i Jekyll (Ruby) to najpopularniejsze. Wrzucasz plik .md w odpowiedni folder, dodajesz frontmatter YAML z tytułem i datą – i masz stronę. Zero bazy danych, zero CMS-a, pełna kontrola nad kodem źródłowym. SSG i Markdown to naturalna para: treść piszesz w zwykłym edytorze, a na końcu generujesz strony. Kiedyś używałem Jekylla, ale zatrzymał się w rozwoju. Wybrałem Hugo dla mojej strony internetowej. Przejście z Jekylla na Hugo wymagało tylko przeniesienia folderów z plikami Markdown!

Istnieją też narzędzia pośrednie: Strapi i Ghost obsługują Markdown jako format edycji. WordPress ma block editor, który natywnie wspiera Markdown. Markdown jako format źródłowy jest wszędzie – nawet tam, gdzie go nie widać w UI.

Markdown nie jest idealny.

· Tabele – działają, ale przy złożonych danych lepiej sprawdza się HTML

· Zakładki, karty, interaktywne elementy – wymagają rozszerzeń (callouts w Obsidianie, admonitions w GitHubie)

· Multimedia – audio, wideo wymagają HTML (ale <video> w MD działa)

· Różne dialekty – GitHub Flavored Markdown różni się od Obsidian MD, różni się od MultiMarkdown

Ale to są ograniczenia formatu, nie koncepcji. Nawet z nimi, Markdown wygrywa w kategorii “najlepszy kompromis między prostotą a możliwościami”.

· Autorzy treści – jeśli piszesz w Wordzie i wrzucasz do CMS-a, zastanów się nad MD jako formatem źródłowym

· Specjaliści dostępności – Markdown może być narzędziem do tworzenia dostępnych treści by design, nie po kosztach

· Devowe – już jesteście w MD, pomyślcie o dostępności w dokumentacji

· Badacze i projektanci AI – format wejściowy ma znaczenie; MD to jeden z lepszych wyborów

· Naukowcy – za Dominikiem Batorskim: publikujcie w Markdown obok PDF

Markdown nie jest kolejnym formatem. Jest lingua franca:

· Człowiek: czyta i pisze naturalnie

· AI: rozumie strukturę bez szumu

· Sieć: HTML jest krokiem dalej, ale źródłem jest MD

· Przyszłość: dokumenty zarządzane przez AI będą prawdopodobnie żyć w MD

W kontekście dostępności to szczególnie ważne: format, który z założenia oddziela treść od prezentacji i wymusza semantyczną strukturę, jest lepszym punktem wyjścia do tworzenia dostępnych treści niż jakikolwiek edytor WYSIWYG.

Nie chodzi o to, żeby wszyscy pisali w edytorze tekstu. Chodzi o to, żeby źródło było czyste. AI to doceni. Czytelnicy to docenią. A dostępność będzie nie dodatkiem, tylko naturalną cechą.

I to by było na tyle. Nie mam dzisiaj wieści o dostępności, bo tutejszy internet nie nadaje się do szukania informacji. Siedzimy w domku w Gąskach nad Bałtykiem. W domku, bo wietrzysko takie, że łeb urywa. Mam w głowie złośliwości kierowane w kierunku pięknego prezydenta USA, ale to za proste. . A zatem tylko pozdrowię Cię i do kolejnego Dostępnika lub spotkania.