Nejoblíbenější knihovna pro HTML na Markdown neumí převádět tabulky

turndown byl v okamžiku snímku metadat nejpopulárnější ze čtyř testovaných knihoven podle počtu hvězdiček na GitHubu, měl jich 11 386. Na čtyřech společných HTML ukázkách ale při výchozím nastavení vygeneroval nulový počet Markdown tabulek a pro stejný vstup použil o 24,6 % více tokenů než markdownify.

Všechny čtyři nástroje zachovaly všech 16 testovacích obsahových probeů. Rozdíly jsou čistě v tom, co se stane se strukturou — a kolik vás tato struktura bude stát dál v řetězci.

Co se měřilo a na jakých ukázkách

Tento výzkumný základ už měl připravený balíček pro markitdown s pěti HTML ukázkami a předregistrovanými testovacími řetězci — přesnými texty, u nichž se ověřovalo, zda přežijí převod, plus pomocnými boilerplate řetězci pro odhalení „chrome“ stránky. Pro agregované srovnání byly použity čtyři ukázky společné pro všechny čtyři převodníky: katalog knihkupectví, web s citáty, tabulka hokejových statistik a článek Wikipedie o web scrapingu. Pátá ukázka, Nothing but tables, slouží jen jako diagnostika zaměřená na tabulky a do souhrnného výpočtu 24,6 % není zahrnuta.

Čtveřice nástrojů: turndown 7.2.4 (Node), markdownify 1.2.3, html2text 2025.4.15 a markitdown, u něhož jsou použité zveřejněné hodnoty beze změn. Stránky: katalog knihkupectví, web s citáty, tabulka hokejových statistik a článek Wikipedie o web scrapingu.

Názvy metrik níže přesně odpovídají políčkům v artefaktu markitdown, takže řádky lze porovnávat přímo vedle sebe bez toho, aby bylo nutné sjednocovat dvě různé definice stejného slova.

Tabulka

Čtyři ukázky — stejné, jaké testoval i markitdown. Kompletní čísla po jednotlivých ukázkách jsou v fiveway-scores.json. Tokeny byly počítány pomocí o200k_base; řádky tabulek u markitdown byly přepočítány z jeho uloženého Markdownu stejným čítačem jako u ostatních.

Zachování obsahu je remíza. Všech šestnáct obsahových probeů napříč čtyřmi ukázkami přežilo u každého převodníku. Pokud vás zajímá jen to, zda text projde dál, všechny čtyři odpovědi zní ano.

Struktura ale remíza není. Na čtyřech společných ukázkách markdownify i markitdown generují 36 řádků Markdown tabulek; html2text generuje 32; turndown negeneruje žádný. V samostatné diagnostice zaměřené jen na tabulky vytvořil markdownify 62 řádků a html2text 59; tyto řádky nejsou v agregovaném výpočtu výše zahrnuty.

Náklad na tokeny je u turndown o 24,6 % vyšší, a důvodem nejsou tabulky. Původně jsem si myslel, že ano, ale čísla po jednotlivých ukázkách ukazují něco jiného — viz níže.

Co turndown udělá s tabulkou

Tady je ukázka s hokejovými statistikami, stejné řádky ve třech podobách.

turndown:

Team Name

Year

Wins

Losses

Boston Bruins

1990

44

24

markdownify:

| Team Name | Year | Wins | Losses | ... |
| --- | --- | --- | --- | --- |
| Boston Bruins | 1990 | 44 | 24 | ... |

html2text:

Team Name  |  Year  |  Wins  |  Losses  | ...
---|---|---|---|---
Boston Bruins  |  1990  |  44  |  24  | ...

Každá hodnota turndownovým převodem projde, a proto má skóre 16/16 v probech. Co ale nepřežije, je přiřazení každé hodnoty ke správnému sloupci. Když čtete výstup turndown, číslo 44 je jen číslo na řádku; bez počítání pozic a spoléhání na to, že žádná buňka nebude prázdná, nepoznáte, že jde o počet výher Bostonu. V této ukázce ale některé buňky prázdné jsou, takže ani počítání pozic nefunguje.

Pro model, který výstup čte, je to rozdíl mezi tabulkou, na kterou umí odpovědět, a seznamem čísel, u nichž bude hádat.

To není ani tak chyba jako spíš zdokumentované omezení — jádro turndown tabulky neumí, a k jejich doplnění existuje turndown-plugin-gfm. Jenže základní instalace ho neobsahuje a 11 386 hvězdiček naznačuje, že spousta lidí používá výchozí variantu.

Odkud se ve skutečnosti bere rozdíl v tokenech

Výše uvedený odstavec jsem napsal s přesvědčením, že 24,6% rozdíl v tokenech způsobují zploštělé tabulky promítající se do počtu znaků. Pak jsem se podíval na čísla po jednotlivých ukázkách — a nebylo to ono.

Na ukázce, která je jen o tabulkách, je turndown o 22 % levnější — protože i podpůrné „pipe“ konstrukce něco stojí a turndown je vůbec negeneruje. Samotné zploštění tabulky tedy samo o sobě tokenový trest nepředstavuje.

Wikipedická ukázka tvoří 74 % celku a obsahuje jen devět řádků tabulky. Její rozdíl 15 378 znaků nemůže být způsoben tabulkami. Je to toto:

(function(){var className="client-js vector-feature-language-in-header-enabled…
.mw-parser-output cite.citation{font-style:inherit;word-wrap:break-word}…
(RLQ=window.RLQ||[]).push(function(){mw.config.set({"wgHostname":"mw-web…

turndown neodstraňuje obsah <script> a <style>. markdownify i html2text ano. Když se to spočítá podle markerů, které se vyskytují jen uvnitř těchto elementů, turndownův výstup nese napříč ukázkami 10 script markerů a 84 style markerů; oba ostatní nástroje mají u obou položek nulu. Na stránce Wikipedie tvoří osm řádků vložené JavaScriptové konfigurace a CSS v MediaWiki 14 644 znaků — 95 % celého rozdílu (script-style-stripping.json).

To je zjištění, podle kterého bych se skutečně řídil. Zploštělá tabulka je problém struktury, který je vidět. Blok JavaScriptové konfigurace v Markdownu je čistý náklad bez jakékoli informační hodnoty a na reálné stránce převažuje úplně všechno ostatní v tomto srovnání.

html2text zapisuje tabulky způsobem, který nemusíte poznat

html2text získal 32 řádků tam, kde markdownify a markitdown získaly 36, a první verze mého čítače mu připsala 1.

To ale nebyla chyba knihovny, nýbrž moje pravidlo počítání. html2text vypisuje Team Name | Year | Wins bez úvodních a koncových svislých čar — což je běžná Markdown tabulková forma, ale pro regulární výraz vyžadující ^\|.*\|$ neviditelná. Napsal jsem ten regex, spustil ho a byl připraven tvrdit, že html2text tabulky neumí.

Umí. Opravený čítač používá heuristiku: souvislý blok řádků obsahujících svislé čáry, uvnitř kterého je oddělovací řádek. Podle tohoto pravidla se html2text posune z 1 na 32. Není to plnohodnotný Markdown parser, takže čísla řádků je třeba číst jako měření podle zdokumentovaného čítače, nikoli jako univerzální výsledky renderování.

To je dobré vědět, pokud Markdown dál zpracováváte vlastními regexy: dvě z těchto čtyř knihoven zapisují tabulky s vnějšími svislými čarami a jedna ne.

Licence, o které se nikdo nezmiňuje

install-and-import.json. Každá knihovna byla nainstalována do vlastního prázdného prostředí. Licence byly ověřeny ze tří zdrojů: z metadat registru, z GitHub repozitáře a z vlastního souboru METADATA nainstalovaného balíčku, kde je uvedeno License-Expression: GPL-3.0-or-later.

Nejlehčí knihovna v tomto srovnání instalace — 1 balíček, 0,2 MiB — je pod licencí GPL-3.0-or-later. To, zda je to problém, závisí na tom, jak je software kombinován a distribuován. Berte to jako kontrolní bod pro toho, kdo odpovídá za licence; tento článek není právní rada. markitdown je zde uveden bez měření, protože jeho instalace a licence nebyly v tomto konkrétním artefaktu zachyceny.

Tento kompromis je snadné přehlédnout, protože licence je vlastnost, která se v benchmarku vůbec neprojeví.

Všechny tři jsou výrazně lehčí než knihovny pro extrakci článků ve stejné kategorii — ty se pohybují mezi 21 a 70 MiB. Převodník je mnohem menší nástroj než extraktor a v rozpočtu závislostí je dobré je oddělovat.

Dvě matoucí věci, které jsem musel opravit, aby tahle tabulka byla pravdivá

Čísla výše jsou třetí verze. První dvě byly špatně způsoby, které stojí za pojmenování, protože oba se dají snadno zopakovat.

Pět ukázek proti čtyřem. markitdown zpracoval čtyři z těchto pěti souborů; ostatní tři nástroje všechny pět. Když se každý nástroj sečetl na vlastním souborovém souboru, vyšlo markdownify 98 řádků tabulek proti 36 u markitdown a vypadalo to jako mezera ve schopnostech. Na stejných čtyřech ale jde o 36 proti 36 — přesná remíza. Pátá ukázka je ta nejvíc tabulková, takže tato matoucí okolnost působila nejhorším možným směrem a novější nástroje nafukovala proti původnímu téměř trojnásobně.

Dva čítače, jeden sloupec. Zveřejněná hodnota md_table_rows u markitdown pocházela z jeho vlastního kódu, který jsem si nepřečetl. Porovnávání tohoto čísla s mým by mohlo znamenat srovnávání dvou čítačů, nikoli dvou převodníků. Jeho Markdown výstup je uložený na disku, takže oprava spočívala v tom, že jsem na všechny čtyři spustil jeden čítač — a když jsem to udělal, přepočet markitdown vyšel přesně na jeho zveřejněné hodnoty na jednotlivou ukázku (0, 0, 27, 9). Definice se shodovaly; jen jsem to nemohl vědět, dokud jsem to neověřil.

Ani jedna chyba by ve výstupu nebyla vidět. Obojí by přineslo sebevědomě, ale chybně vyplněnou tabulku.

Kdo by měl použít co

Krmit model nebo ukládat strukturovaný obsah ze stránek jako jsou tyto? Začněte s markdownify. Podle tohoto čítače se vyrovná markitdown v počtu vygenerovaných řádků tabulek, patří do skupiny s nejnižší spotřebou tokenů, je pod licencí MIT a nainstaluje se do 1,8 MiB. Než ho standardizujete, ověřte ho na vlastních typech stránek.

Rozpočet závislostí měříte v kilobytech a software dál nedistribuujete? html2text. Jeden balíček, 0,2 MiB, tabulky zachované. Nejdřív si ověřte otázku licence GPL a počítejte s tím, že poslední vydání bylo v dubnu 2025.

Už jedete na Node stacku? turndown, ale spolu s turndown-plugin-gfm — a před předáním HTML odstraňte <script> a <style>, protože turndown to neudělá. Tato dvě opomenutí stojí čtvrtinu tokenů navíc i strukturu tabulek a nic z toho neuvidíte, dokud se nepodíváte na výstup.

Už převádíte i jiné formáty dokumentů? markitdown zvládá PDF, Office a další a jeho HTML výstup je konkurenceschopný vůči specializovaným převodníkům. Jeden závislostní balíček místo dvou je také něco.

Kam zapadá spravované API

Všechny čtyři nástroje pracují s HTML, které už máte. Žádný z nich stránku nestahuje, nespouští JavaScript ani neřeší anti-bot vrstvu — a u mnoha reálných cílů je právě tohle ta těžší polovina.

Náš vlastní vývojářský stack v Thunderbit pokrývá právě tuto část. POST /distill vezme URL a vrátí čistý Markdown připravený pro LLM, přičemž renderování i načtení stránky řeší za vás; POST /extract vrací strukturovaný JSON odpovídající AI schématu podle JSON Schema, které zadáte — tedy zase jiný výstupní tvar, tentokrát řádky místo Markdown tabulky, kterou byste pak museli parsovat. Oba endpointy jsou dostupné přes MCP server i CLI (npx @thunderbit/thunderbit-cli). Ceník je na stránce s cenami Thunderbit.

Upřímné srovnání: pokud už HTML máte a chcete Markdown, markdownify je zdarma a svou práci odvede dobře — a tahle tabulka ukazuje, které z jeho soupeřů to umí také. Pokud stránky teprve stahujete, nebo chcete strukturované řádky místo prozaického textu, je to jiný nákup.

Širší přehled trhu najdete v našem souhrnu web scraping API a v přehledu open-source scraperů pro self-hosted řešení. Praktický postup nabízí článek Převod HTML na Markdown v Pythonu a text co se snaží standardizovat llms.txt popisuje, kam se tato kategorie ubírá.

Vyzkoušejte Thunderbit pro extrakci webových dat

Verdikt

Pro tento čtyřukázkový workload je markdownify nejsilnější výchozí volba: stejný počet vygenerovaných řádků tabulek jako markitdown podle sdíleného čítače, počet tokenů do 1,3 % od ostatních efektivních převodníků, licence MIT a instalace o velikosti 1,8 MiB.

Právě ten rozdíl mezi popularitou a měřeným chováním je hlavní zjištění. turndown je výborná knihovna, kterou si mnoho lidí nainstalovalo bez pluginu, jenž z ní dělá nástroj schopný pracovat s tabulkami, a cena za to se projeví jako čtvrtina tokenů navíc a tabulková struktura, která už neexistuje. Ani jedno číslo nikde nevidíte, dokud je nezačnete počítat.

Jestli si odnesete jen jednu věc: než budete výstupu důvěřovat v modelu, zkontrolujte, co váš převodník udělá s tabulkou. Tři ze čtyř dělají něco rozumného. Ten nejpopulárnější ne — pokud jste ho k tomu výslovně nepřivedli.

Vyzkoušejte Thunderbit pro extrakci webových dat Get Started Free

Nejčastější dotazy

Opravdu turndown nepodporuje tabulky? Jeho jádro ne. Tabulky dodává až turndown-plugin-gfm, samostatný balíček, a obyčejné npm install turndown ho neobsahuje. Bez pluginu projde každá buňka jako samostatný odstavec — hodnoty tam jsou všechny, ale vztah řádků a sloupců ne. Napříč čtyřmi ukázkami to dalo nulový počet Markdown tabulek a o 24,6 % více tokenů než markdownify pro stejný obsah.

Proč to na začátku vypadalo, že html2text žádné tabulky nemá? Protože můj čítač vyžadoval úvodní i koncové svislé čáry a html2text je nevypisuje. Team Name | Year | Wins je validní Markdown a rendruje se správně; jen používá jiný styl než | Team Name | Year |. Opravený čítač hledá souvislý blok řádků se svislými čarami a oddělovací řádek, podobně jako parser, a html2text se tak dostane z 1 řádku na 32. Pokud Markdown dál zpracováváte vlastními regexy, právě tady narazíte.

Je GPL u html2text skutečný problém? Záleží na tom, jak software kombinujete a distribuujete. GPL-3.0-or-later může vytvářet povinnosti, které MIT nemá, proto do výběru zapojte toho, kdo odpovídá za licence, ještě před nasazením do distribuovaného produktu. To je kontrola souladu, ne právní rada; identita licence byla potvrzena v metadatech registru, v repozitáři i ve vlastním souboru METADATA nainstalovaného balíčku.

Jsou tyto tokenové počty relevantní i pro jiné stránky? Rozdíl 24,6 % je z velké části daný tím, že turndown ponechává obsah <script> a <style>, takže jeho velikost roste podle toho, kolik takového obsahu stránka má — na moderním CMS hodně, na statické stránce téměř vůbec. Tabulky to naopak posouvají jinam: na ukázce, která je jen o tabulkách, byl turndown o 22 % levnější, protože negeneruje žádné „pipe“ lešení. Bajtů na token se u všech čtyř drželo mezi 3,61 a 3,65, takže hustota výstupu je všude stejná a rozdíl je v objemu. Pokud na čísle záleží rozpočtu, změřte si vlastní korpus.

Co se tu netestovalo? Skutečná různorodost webu — čtyři ukázky jsou pořád jen čtyři ukázky. Vnořené seznamy, definicové seznamy, poznámky pod čarou a matematika. Chybně zapsané HTML, kde se převodníky historicky rozcházejí nejvíc. Převod Markdownu zpět do HTML. docling, který má na disku stejné ukázky, ale jeho zveřejněný běh neuvádí tato pole, takže tu není ani odhadovaný. A konfigurace: html2text byl spuštěn s body_width=0, protože jeho výchozích 78 znaků by tvrdě zalamovalo každý řádek, což by změnilo každý znak i počet tokenů v této tabulce.