Dokumentace pluginu Toret AI Markdown

🔗 Dostupné URL

URL	Popis
`https://vasedomena.cz/stranka/?format=markdown`	Markdown verze libovolné stránky nebo příspěvku
`https://vasedomena.cz/?format=markdown-sitemap`	Přehled všech dostupných stránek pro AI agenty
`https://vasedomena.cz/llms.txt`	Instrukce a kontext pro AI agenty

🏷️ Link tag v hlavičce

Pokud je zapnuta volba Link tag v hlavičce, plugin vloží do <head> každé stránky následující meta tagy:

<link rel="alternate" type="text/markdown" href=".../llms.txt" title="Site Context" />
<link rel="alternate" type="text/markdown" href=".../?format=markdown" title="Page Context" />
<link rel="alternate" type="text/markdown" href=".../?format=markdown-sitemap" title="Markdown Sitemap" />

AI agenti tento tag používají k tzv. autodiscovery – automaticky zjistí, že existuje Markdown verze stránky, a použijí ji pro lepší a přesnější porozumění obsahu.

📊 Barvy v logu přístupů

Zelená – OpenAI / GPTBot
Oranžová – Anthropic / ClaudeBot
Modrá – Google / Googlebot
Modrofialová – Bing / Microsoft
Růžová – Jiní AI roboti (Perplexity, Cohere, Amazon SearchBot, ByteSpider…)
Šedá – Neznámý návštěvník

🔧 WordPress filtry pro vývojáře (Přehled)

Filtr	Popis
`toret_markdown_post_frontmatter`	Úprava YAML hlavičky postu před uzavřením
`toret_markdown_post_output`	Výsledný Markdown stránky / produktu
`toret_markdown_term_output`	Výsledný Markdown taxonomie (kategorie, tag)
`toret_markdown_archive_output`	Výsledný Markdown archivu, homepage, shopu
`toret_markdown_sitemap_pages_args`	Argumenty `get_pages()` v sitemapě
`toret_markdown_sitemap_posts_args`	Argumenty `get_posts()` v sitemapě
`toret_markdown_sitemap_products_args`	Argumenty `wc_get_products()` v sitemapě
`toret_markdown_sitemap_products`	Pole produktů po načtení (filtrování objektů)
`toret_markdown_sitemap_output`	Celý výsledný text sitemapy

🤖 Co plugin dělá

Toret Markdown přidává ke každé stránce WordPressu alternativní výstup ve formátu Markdown. Ten je určen primárně pro AI jazykové modely a agenty (ChatGPT, Claude, Perplexity…), kteří text v Markdownu zpracovávají přesněji a efektivněji než běžné HTML.

Plugin generuje tři typy výstupů:

Stránka / příspěvek / produkt — ?format=markdown
Sitemap pro AI — ?format=markdown-sitemap
llms.txt — instrukce a kontext na kořeni webu

🚀 Rychlý start

1. Zapněte plugin

V administraci WordPressu přejděte do Toret plugins > AI Markdown (záložka Nastavení) a ujistěte se, že je přepínač Plugin je aktivní zaškrtnutý.

2. Otestujte výstup

Přidejte ?format=markdown na konec libovolné URL vašeho webu, např.:
https://vasedomena.cz/stranka/?format=markdown

3. Nastavte llms.txt

V administraci pluginu přejděte do záložky llms.txt a upravte instrukce pro AI agenty. Soubor je pak veřejně dostupný na adrese https://vasedomena.cz/llms.txt.

4. Zkontrolujte sitemapu

Sitemap pro AI je dostupná na adrese https://vasedomena.cz/?format=markdown-sitemap. Obsahuje přehled všech veřejných stránek s jejich popisem.

⚙️ Popis nastavení

Link tag v hlavičce

Pokud je zapnuto, plugin vloží do <head> každé stránky tag <link rel="alternate" type="text/markdown">. Moderní AI agenti tento tag rozpoznají a automaticky si načtou Markdown verzi místo HTML — bez jakéhokoliv zásahu z vaší strany.

HTTP timeout

Plugin generuje Markdown tak, že interně načítá (fetchuje) HTML stránky a převádí ho. Timeout určuje, jak dlouho na odpověď čekat. Při pomalém hostingu nebo obzvlášť velkých stránkách doporučujeme zvýšit hodnotu na 30–60 s.

Blacklist slugů

Jeden slug na řádek. Stránky, které jsou na blacklistu, nevrátí Markdown výstup a nezobrazí se ani v sitemapě. Typicky sem patří technické stránky bez relevantního obsahu: cart, checkout, my-account, thank-you.

Logování přístupů

Plugin loguje každý přístup na ?format=markdown a ?format=markdown-sitemap včetně identifikace bota (GPTBot, ClaudeBot, Googlebot…). IP adresy jsou automaticky anonymizovány. Záznamy si prohlédnete v záložce Log přístupů.

Max. záznamů logu

Po překročení limitu se automaticky promazávají nejstarší záznamy. Doporučená hodnota je 500–1000 pro běžné weby.

✏️ Editor Markdown

Jak funguje cache

Plugin generuje Markdown automaticky při každém přístupu. Výsledek se uloží do cache (jako post meta), takže opakované požadavky jsou velmi rychlé a nevytěžují server. Cache se automaticky obnoví při jakékoliv úpravě příspěvku.

Ruční editace

V záložce Editor můžete Markdown libovolné stránky ručně upravit a uložit. Po uložení se cache zamkne — plugin ji už dál nebude automaticky přepisovat. Zámek lze kdykoliv odemknout tlačítkem přímo v editoru.

Zamčená cache

Stránky se zamčenou cache jsou v editoru označeny ikonou 🔒. Znamená to, že web AI agentům zobrazí přesně ten obsah, který jste ručně nastavili — plugin ho nepřepíše ani při následné aktualizaci příspěvku.

🗺️ Sitemap pro AI

Co sitemap obsahuje

Sitemap je přehled všech veřejných stránek, příspěvků a produktů ve formátu Markdown. Pro každou položku obsahuje název, URL, datum úpravy a krátký popis. AI agent ji použije k tomu, aby zjistil, co všechno na webu existuje, a poté si načetl detaily konkrétních stránek.

Ruční přepsání

V záložce Sitemap můžete dynamicky generovaný obsah přepsat vlastním textem a uložit ho. Tlačítkem Obnovit dynamickou sitemapu jednoduše vrátíte automatické generování.

Limity a řazení

V záložce Nastavení lze pro každý typ obsahu (stránky, příspěvky, produkty) nastavit maximální počet položek a způsob jejich řazení. Hodnota -1 nebo 0 znamená výpis bez limitu.

🤖 llms.txt

K čemu slouží

llms.txt je standardizovaný soubor (funguje podobně jako robots.txt), který AI agentům říká, jak s vaším webem správně pracovat. Doporučujeme sem napsat: kdo jste, co nabízíte, jaké stránky jsou pro AI nejdůležitější a jaká pro ně platí omezení.

Výchozí obsah

Tlačítkem Obnovit výchozí obsah v záložce llms.txt plugin automaticky vygeneruje základní obsah z dat vašeho WordPressu (název webu, popis, kontakt, URL sitemapy). Výsledek pak stačí jen doplnit nebo ručně upravit.

📄 Metabox na stránkách a produktech

Kde se zobrazí

Metabox Toret Markdown se zobrazuje v pravém sloupci editoru u každého příspěvku, stránky i produktu. Ukazuje aktuální stav cache (aktuální / nevygenerovaná / vyloučená) a přesné datum posledního generování.

Generovat / Přegenerovat

Tlačítkem Generovat (nebo Přegenerovat) spustíte okamžité vygenerování Markdown cache pro danou stránku přímo z administrace, bez nutnosti ji navštívit. Po vygenerování se zobrazí odkaz Náhled pro kontrolu výstupu.

Vyloučit z Markdown

Stránka nebude vracet žádný Markdown výstup — místo toho se AI zobrazí běžné HTML. Zároveň se nevloží <link> tag do hlavičky a daná stránka se nezahrne do sitemapy.

Zamknout cache

Zabrání automatickému přegenerování cache při uložení stránky. Hodí se, když jste Markdown ručně upravili v editoru a nechcete, aby ho plugin omylem přepsal. Zámek lze kdykoliv zrušit nebo odemknout přímo v editoru.

Skrýt ze sitemapy

Stránka se sice nezobrazí v ?format=markdown-sitemap, ale její Markdown verze zůstane plně dostupná přes ?format=markdown. Rozdíl oproti Vyloučit z Markdown je ten, že obsah stále existuje, jen se neobjeví v globálním přehledu pro AI.

Odkaz do editoru

Odkaz Upravit Markdown v editoru v dolní části metaboxu vás přenese přímo do záložky centrálního Editoru s předvybranou aktuální stránkou.

🗂️ Nastavení u kategorií

Kde se zobrazí

Panel Toret Markdown se zobrazuje na stránce úpravy kategorie příspěvků (Příspěvky → Kategorie). Pokud je aktivní WooCommerce, funguje naprosto stejně i u kategorií produktů (Produkty → Kategorie).

Vyloučit z Markdown

Stránka kategorie nebude vracet Markdown výstup a nevloží se do ní <link> tag v hlavičce. Funguje stejně jako stejnojmenná volba v metaboxu u jednotlivých příspěvků.

Skrýt ze sitemapy

Kategorie se nezobrazí v ?format=markdown-sitemap, ale její Markdown verze zůstane dostupná přes ?format=markdown. Na stránce úpravy kategorie je také přímý odkaz Náhled Markdown pro rychlé zobrazení výstupu.

🛒 WooCommerce

Produkty v sitemapě

Pokud je WooCommerce aktivní, sitemap automaticky zahrne i produkty včetně jejich ceny, skladovosti a kategorie. V nastavení lze produkty filtrovat podle kategorie nebo omezit jejich celkový počet.

Frontmatter produktu

Markdown výstup produktové stránky obsahuje chytře rozšířenou YAML hlavičku s cenou (price), měnou (currency), skladovostí (in_stock) a SKU. AI agent díky tomu zná přesný a aktuální stav produktu bez nutnosti složitě parsovat HTML.

Kategorie produktů

Na stránce kategorie produktů v administraci (Produkty → Kategorie) najdete metabox pro případné vyloučení celé kategorie z Markdown výstupu a ze sitemapy.

📌 Konstanty

Konstanta	Hodnota	Popis
`TORET_MARKDOWN_CACHE_KEY`	`_toret_markdown_cache`	Post meta klíč pro uložený Markdown
`TORET_MARKDOWN_META_EXCLUDE`	`_toret_markdown_exclude`	Post meta – vyloučení z Markdown výstupu
`TORET_MARKDOWN_META_LOCK`	`_toret_markdown_lock`	Post meta – zámek automatické regenerace cache
`TORET_MARKDOWN_META_SITEMAP_EXCLUDE`	`_toret_markdown_sitemap_exclude`	Post meta – skrytí ze sitemapy
`TORET_MARKDOWN_TERM_EXCLUDE`	`_toret_markdown_exclude`	Term meta – vyloučení kategorie z Markdown
`TORET_MARKDOWN_TERM_SITEMAP_EXCLUDE`	`_toret_markdown_sitemap_exclude`	Term meta – skrytí kategorie ze sitemapy
`TORET_MARKDOWN_LOG_OPTION`	`toret_markdown_access_log`	Options klíč pro log přístupů
`TORET_MARKDOWN_LOG_MAX`	`500`	Výchozí max. počet záznamů logu

🪝 WordPress filtry (Hooks)

`toret_markdown_post_frontmatter`

Umožňuje upravit YAML frontmatter příspěvku/stránky před uzavíracím ---. Parametry: string $frontmatter, WP_Post $post.

add_filter( 'toret_markdown_post_frontmatter', function( $fm, $post ) {
    $fm .= 'author: ' . get_the_author_meta( 'display_name', $post->post_author ) . "\n";
    return $fm;
}, 10, 2 );

`toret_markdown_post_output`

Výsledný Markdown příspěvku/stránky včetně frontmatteru. Parametry: string $markdown, WP_Post $post.

add_filter( 'toret_markdown_post_output', function( $md, $post ) {
    return $md . "\n\n---\n*Generováno automaticky.*\n";
}, 10, 2 );

`toret_markdown_term_output`

Výsledný Markdown stránky taxonomie (kategorie, tag). Parametry: string $markdown, WP_Term $term.

`toret_markdown_archive_output`

Výsledný Markdown archivní stránky (homepage, shop, archive, search). Parametry: string $markdown, string $type, string $title.

`toret_markdown_sitemap_pages_args`

Argumenty předávané funkci get_pages() při generování sitemapy. Parametr: array $args.

`toret_markdown_sitemap_posts_args`

Argumenty předávané funkci get_posts() při generování sitemapy. Parametr: array $args.

`toret_markdown_sitemap_products_args`

Argumenty předávané funkci wc_get_products() při generování sitemapy. Parametr: array $args.

`toret_markdown_sitemap_products`

Pole WooCommerce produktů po načtení, před jejich renderováním do sitemapy. Umožňuje filtrovat nebo libovolně seřadit objekty. Parametr: array $products.

`toret_markdown_sitemap_output`

Celý výsledný text dynamicky generované sitemapy. Parametr: string $output.

💾 Cache logika

Ukládání

Vygenerovaný Markdown se ukládá jako post meta s klíčem _toret_markdown_cache spolu s časovým razítkem v _toret_markdown_generated_at. Cache se používá pouze pro příspěvky/stránky/produkty — pro termy (kategorie) a archivy se generuje vždy dynamicky.

Invalidace

Cache se automaticky smaže při uložení nebo smazání příspěvku (save_post, before_delete_post), pokud na ní není nastaven zámek (_toret_markdown_lock). Ruční smazání celé cache pro celý web je dostupné v záložce Nastavení.

Generování

Plugin generuje Markdown tak, že si interně stahuje (fetchuje) HTML stránky přes wp_remote_get() a parsuje výsledek vlastním DOM konvertorem (toret_html_to_markdown()). K URL se přidává speciální parametr _tmcb={timestamp} pro efektivní obejití CDN cache (Cloudflare apod.).

⚙️ Převodník HTML → Markdown

Implementace

Plugin k převodu nepoužívá žádnou externí knihovnu. Převod zajišťuje nativní PHP DOMDocument v kombinaci s rekurzivním walkerem toret_dom_node_to_markdown(). Výstup na konci prochází čistící funkcí toret_cleanup_markdown().

Zahozené tagy

Obsah tagů <script>, <style>, <form>, <noscript>, <canvas> a <svg> se zcela ignoruje a do finálního výstupu se vůbec nepřenáší.

Složité seznamy

Plugin automaticky detekuje „složité“ elementy <ul> (např. blog listing, výpis produktů). Položky delší než 100 znaků nebo ty obsahující nadpisy se pak renderují jako jasné sekce oddělené --- místo klasických odrážek.

Cloudflare email

Plugin rozpozná Cloudflare email ochranu (/cdn-cgi/l/email-protection#…) a automaticky dekóduje skutečnou e-mailovou adresu přímo do čitelného výstupu.

🔌 AJAX endpointy

Action	Nonce	Popis
`toret_markdown_generate`	`toret_markdown_ajax_generate`	Vygeneruje nebo přegeneruje Markdown cache pro daný `post_id`. Vyžaduje administrátorské oprávnění `edit_posts`.
`toret_markdown_unlock_cache`	`toret_markdown_unlock_cache`	Odemkne zamčenou cache příspěvku — smaže meta `_toret_markdown_lock`. Vyžaduje oprávnění `edit_post` pro daný post.

🤖 Detekce botů

Rozpoznávání agenti

Detekce probíhá porovnáváním User-Agent hlavičky z prohlížeče (case-insensitive). Rozpoznávané typy a jejich barvy v logu jsou:

gpt — GPTBot, ChatGPT-User, OAI-SearchBot
claude — ClaudeBot, Claude-User, Claude-SearchBot, Anthropic
google — Googlebot, Google-Extended, Gemini, GoogleOther
bing — Bingbot, BingPreview, MSNBot
other_ai — PerplexityBot, Cohere-AI, YouBot, Diffbot, ByteSpider, AmazonBot a další
unknown — nerozpoznaný User-Agent

🗄️ Databáze – uložené hodnoty

Option / Meta klíč	Typ	Popis
`toret_markdown_options`	option	Veškerá nastavení pluginu jako serializované pole
`toret_markdown_access_log`	option	Log přístupů jako JSON pole (max. záznamů dle nastavení)
`toret_markdown_sitemap_content`	option	Ručně přepsaný obsah sitemapy (prázdné = dynamické generování)
`toret_markdown_llms_content`	option	Obsah souboru llms.txt
`_toret_markdown_cache`	post meta	Vygenerovaný Markdown obsah příspěvku
`_toret_markdown_generated_at`	post meta	Datum a čas posledního vygenerování cache
`_toret_markdown_exclude`	post/term meta	Vyloučení z Markdown výstupu
`_toret_markdown_lock`	post meta	Zámek automatické regenerace cache
`_toret_markdown_sitemap_exclude`	post/term meta	Skrytí ze sitemapy