Strona czytelna dla AI: llms.txt i Markdown

Co dostaje agent, który otwiera stronę

Gdy ChatGPT, Claude albo Perplexity pobiera stronę, dostaje to samo co przeglądarka: menu, baner cookies, znacznik skryptu dla każdego pakietu JavaScript, czcionki, analitykę i stopkę z dziesiątkami linków. Płaci tokenami za każdy z tych bajtów, a potem musi sam znaleźć w nich właściwą treść.

Vercel zmierzył jedną ze swoich stron: około 500 KB HTML wobec 3 KB Markdownu, czyli o 99,37% mniej. Moje strony są lżejsze, ale różnica też jest wyraźna: artykuł, w którym to opisuję, waży 29 KB jako HTML i 9,1 KB jako Markdown.

Wersja Markdown ma tę samą treść, bez całej reszty: nagłówki, akapity, listy, linki i kod.

Kiedy to ma znaczenie

Gdy ludzie pytają ChatGPT, Claude’a albo Perplexity o produkt, a odpowiedź ma się opierać na treści ze strony.
Gdy dokumentację, blog albo bazę wiedzy czytają agenci programistyczni.
Gdy ma to działać stale, w kodzie i w testach, a nie dzięki jednorazowej wtyczce.

Agentów rzadko wpisuje się dziś w wymagania strony, więc w większości zespołów nikt za to nie odpowiada.

Z czego to się składa

Markdown pod tym samym adresem. Strona odpowiada Markdownem na żądanie z nagłówkiem Accept: text/markdown, a HTML-em na każde inne. Obie wersje powstają z tego samego źródła w tym samym wdrożeniu, więc zmiana treści trafia do obu naraz.
Vary: Accept na obu wersjach. Bez tego CDN może zapamiętać jedną wersję i podawać ją wszystkim: przeglądarki dostaną Markdown, a agenci HTML.
Link alternate w nagłówku każdej strony. Klient, który nie prosi o Markdown, znajdzie w HTML-u adres wersji Markdown.
Plik llms.txt. Krótki opis serwisu i lista najważniejszych stron z linkami do ich wersji Markdown.
Mapa strony w Markdownie. Tytuły, daty i jednozdaniowe streszczenia, żeby agent mógł wybrać, co przeczytać.
Testy. Sprawdzają, że każdy adres odpowiada właściwym formatem, że Markdown zawiera treść ze źródła i że nagłówki dla cache są na miejscu.

Jak to robię

Najpierw pomiar. Pobieram stronę dwa razy, jako przeglądarka i jako agent, i porównuję, co wróciło: format, rozmiar i nagłówki.
Jedno źródło. HTML i Markdown powstają z tej samej treści w tym samym buildzie. Przy CMS-ie zamiana treści z edytora na Markdown odbywa się w tym samym wdrożeniu co HTML.
Reguła przed plikiem. Vercel podaje plik pasujący do adresu, zanim zadziała jakakolwiek reguła przepisywania adresów (rewrite). Dlatego HTML leży pod wewnętrzną ścieżką, a reguła na nagłówek Accept wybiera wersję. W Next.js to samo załatwia reguła beforeFiles.
Sprawdzenie na produkcji. Po wdrożeniu pobieram obie wersje z produkcji i sprawdzam, czy CDN je rozróżnia.

Ta strona działa tak samo

Ta strona też ma wersję Markdown pod tym samym adresem. Sprawdź to w terminalu:

curl -sL -H "accept: text/markdown" https://maciejwiatr.com/pl/strona-czytelna-dla-ai

Albo wciśnij Start poniżej. Tester pobiera stronę dwa razy, jako przeglądarka i jako agent, i porównuje odpowiedzi. Jego interfejs jest po angielsku.

Ready

Press start. Two requests: one as a browser, one asking for markdown.

content-type (html): —
content-type (markdown): —
Vary: —
alternate link: —
llms.txt: —

Sprawdź tę stronę testerem czytelności dla agentów AI

Cały mechanizm opisałem w artykule Making Next.js agent-readable (po angielsku): konfigurację dla Vercela, wersję dla Next.js sprawdzoną w Next.js 16.4 i listę rzeczy, które sprawdzam w code review. Wcześniej, w Mimirze, zbudowałem katalog przetargów nastawiony na SEO, z około 200 000 zaindeksowanych stron.

Pytania

Czy zmieni się to, co widzą ludzie i Google?

Nie. Przeglądarka i każdy klient, który nie prosi o text/markdown, dostaje ten sam HTML co wcześniej. Markdown dostają tylko ci, którzy o niego poproszą albo wejdą pod jego adres z llms.txt lub linku alternate.

Czy trzeba przepisać stronę albo zmienić CMS?

Nie. Na stronie statycznej to głównie konfiguracja routingu i jeden krok w buildzie. Przy CMS-ie dochodzi zamiana treści z edytora na Markdown, w tym samym wdrożeniu co HTML, żeby obie wersje zawsze się zgadzały.

Co, jeśli strona stoi za Cloudflare?

Trzeba ustawić cache. Cloudflare domyślnie rozróżnia odpowiedzi po adresie i kilku stałych nagłówkach. Od lipca 2026 może je rozróżniać także po Accept, ale tylko gdy ten nagłówek doda się w regule cache (Cache Rule). Po wdrożeniu warto pobrać obie wersje i sprawdzić, co zapamiętał cache.

Czy wszyscy agenci proszą o Markdown?

Nie. curl, fetch w Node.js i requests w Pythonie domyślnie wysyłają Accept: */*, a urllib w Pythonie nie wysyła tego nagłówka wcale. Wszystkie dostają HTML. Dla nich jest link alternate w HTML-u i lista adresów w llms.txt.