En Popüler HTML'den Markdown'a Kütüphane Tabloları Dönüştürmüyor

metindeki dört test kütüphanesi arasında metadata anında en çok yıldız alanı turndown oldu; GitHub’da 11.386 yıldızı vardı. Dört ortak HTML örneğinde ise çekirdek varsayılanlarıyla sıfır Markdown tablosu üretti ve aynı girdiler için markdownify'den %24,6 daha fazla token kullandı.

Dört aracın hepsi, içerik probe’larının tamamını eksiksiz geri getirdi. Farklar tamamen yapısal çıktıda ve bu yapının aşağı akışta size neye mal olduğunda ortaya çıkıyor.

Neler ölçüldü ve hangi örnekler üzerinde?

Bu araştırma setinde zaten markitdown için beş HTML örneği ve önceden kaydedilmiş probe dizeleri vardı — birebir korunması beklenen dizeler ile, sayfa süslerini tespit etmek için kullanılan standart metinler. Toplu karşılaştırma, dört dönüştürücünün de ortak kullandığı dört örnek üzerinden yapılıyor: bir kitapçı kataloğu, bir alıntılar sitesi, bir hokey istatistik tablosu ve web kazıma konulu Wikipedia maddesi. Sadece tablolar adlı beşinci örnek ise yalnızca tablo ağırlıklı bir tanılama olarak kullanılıyor ve %24,6’lık toplama dahil edilmiyor.

Dört araç: turndown 7.2.4 (Node), markdownify 1.2.3, html2text 2025.4.15 ve yayınlanmış satırları olduğu gibi kullanılan markitdown. Sayfalar: bir kitapçı kataloğu, bir alıntılar sitesi, bir hokey istatistik tablosu ve web kazıma konulu Wikipedia maddesi.

Aşağıdaki metrik adlarının tamamı markitdown’ın kendi artifact alan adlarıyla birebir eşleşiyor; böylece satırlar, aynı kelimeye ait iki farklı tanımı uzlaştırmaya gerek kalmadan yan yana durabiliyor.

Tablo

Dört örnek — markitdown’ın da çalıştırıldığı aynı set. Örnek bazındaki tam sayılar fiveway-scores.json içinde. Token sayımı o200k_base ile yapıldı; markitdown’ın tablo satırları ise kendi saklanmış Markdown çıktısından, diğerlerinde kullanılan aynı sayaçla yeniden sayıldı.

İçerik korunumu başa baş. Dört örnekteki on altı body probe’unun tamamı, her dönüştürücüde de korundu. Eğer tek sorunuz "metin taşınır mı?" ise, bu dört araç da evet cevabını veriyor.

Yapı korunumu başa baş değil. Dört ortak örnekte markdownify ve markitdown 36’şar Markdown tablo satırı üretirken; html2text 32 satır üretiyor; turndown ise hiç üretmiyor. Ayrı tablo-ağırlıklı tanılama örneğinde markdownify 62, html2text 59 satır üretti; bu satırlar yukarıdaki toplama dahil değil.

Turndown için token maliyeti %24,6 daha yüksek ve bunun sebebi tablolar değil. Ben de başta öyle sandım; ancak örnek bazındaki sayılar bunun böyle olmadığını gösteriyor — aşağıda anlatıyorum.

Turndown bir tabloya ne yapıyor?

Aynı satırlar, hokey istatistik örneğinde üç farklı biçimde şöyle görünüyor.

turndown:

Takım Adı

Yıl

Galibiyet

Mağlubiyet

Boston Bruins

1990

44

24

markdownify:

| Takım Adı | Yıl | Galibiyet | Mağlubiyet | ... |
| --- | --- | --- | --- | --- |
| Boston Bruins | 1990 | 44 | 24 | ... |

html2text:

Takım Adı  |  Yıl  |  Galibiyet  |  Mağlubiyet  | ...
---|---|---|---|---
Boston Bruins  |  1990  |  44  |  24  | ...

Turndown dönüştürmesi sırasında her değer korunuyor; bu yüzden probe’larda 16/16 alıyor. Ama korunmayan şey, her değerin hangi sütuna ait olduğu. Turndown çıktısını okuyunca 44 yalnızca bir satırdaki sayı olarak kalıyor; hücrelerin boş olup olmadığına da bağlı olduğundan, pozisyon sayarak bunun Boston’un galibiyet sayısı olduğunu geri çıkarmak mümkün değil.

Bir model açısından bu, soru cevaplayabileceği bir tablo ile ancak tahminde bulunabileceği bir sayı listesinin farkı demek.

Bu tam anlamıyla bir kusurdan çok, belgelenmiş bir sınır: turndown’un çekirdeği tabloları işlemez; bunun için turndown-plugin-gfm eklenir. Ancak varsayılan kurulumda bu eklenti yok ve 11.386 yıldız, birçok kişinin varsayılan hali kullandığını düşündürüyor.

Token farkı gerçekten nereden geliyor?

Yukarıdaki paragrafı yazarken, %24,6’lık token farkının düzleştirilmiş tabloların karakter olarak görünmesinden kaynaklandığını düşünüyordum. Örnek bazında bakınca öyle olmadığı ortaya çıktı.

Sadece tablolar olan örnekte turndown %22 daha ucuz — çünkü pipe iskeleti de token yer ve turndown bunu hiç üretmiyor. Yani tabloyu düzleştirmek, tek başına token cezası anlamına gelmiyor.

Wikipedia örneği toplamın %74’ünü oluşturuyor ve içinde dokuz tablo satırı var. 15.378 karakterlik farkın kaynağı tablo olamaz. Asıl sebep şu:

(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 <script> ve <style> içeriğini temizlemiyor. markdownify ve html2text ise ikisini de temizliyor. Yalnızca bu öğelerin içinde görülen işaretler sayıldığında, turndown’ın çıktısında örnekler boyunca 10 script işareti ve 84 style işareti var; diğer iki araçta ise sıfır. Wikipedia sayfasında MediaWiki’nin satır içi JavaScript yapılandırması ve CSS’sinden oluşan sekiz satır, 14.644 karaktere — toplam farkın %95’ine karşılık geliyor (script-style-stripping.json).

Benim gerçekten önemseyeceğim bulgu bu olurdu. Düzleştirilmiş bir tablo, görebileceğiniz bir yapı sorunu. Ama Markdown içine düşen bir JavaScript yapılandırma bloğu, hiçbir bilgi taşımadan doğrudan maliyet yaratır; gerçek dünyadaki bir sayfada bu, bu karşılaştırmadaki diğer her şeyi gölgede bırakır.

html2text, ilk bakışta tanıyamayacağınız tablolar yazar

html2text, markdownify ve markitdown’ın 36’şar satırına karşı 32 satır üretti; sayaç sürümümün ilk hali ise onu 1 olarak saydı.

Bu kural benim kuralımdı, kütüphanenin değil. html2text Team Name | Year | Wins çıktısını başta ve sonda pipe olmadan verir — bu, yaygın bir Markdown tablo biçimidir ama ^\|.*\|$ şartı koyan bir regex için görünmezdir. O regexi ben yazmıştım, çalıştırmıştım ve html2text’in tablo üretmediğini rapor etmeye hazırdım.

Ama üretiyor. Düzeltilmiş sayaç, arada ayırıcı satır bulunan ve peş peşe gelen pipe içeren satırları bir desen olarak tanıyor. Bu kuralla html2text 1’den 32’ye çıkıyor. Bu tam bir Markdown ayrıştırıcısı değil; dolayısıyla satır toplamları, evrensel render sonucu değil, belgelenmiş bir sayacın ölçümü olarak okunmalı.

Markdown’ı kendi regex’inizle sonradan işliyorsanız bilmeye değer: bu dört kütüphanenin ikisi dış pipe’larla çıktı verir, biri vermez.

Kimsenin bahsetmediği lisans

install-and-import.json. Her kütüphane kendi boş ortamına kuruldu. Lisanslar üç yerden doğrulandı: kayıt defteri metadata’sı, GitHub deposu ve kurulu paketin kendi METADATA dosyası; burada License-Expression: GPL-3.0-or-later yazıyor.

Bu kurulum karşılaştırmasında en hafif kütüphane — tek paket, 0.2 MiB — GPL-3.0-or-later lisanslı. Bunun bir projeyi etkileyip etkilemeyeceği, yazılımın nasıl birleştirilip dağıtıldığına bağlı. Lisans sorumluluğu kimdeyse onun için bir seçim kontrol noktası olarak düşünün; bu yazı hukuki tavsiye değildir. markitdown burada ölçülmemiş görünüyor, çünkü bu artifact içinde kurulum ve lisans verisi toplanmamış.

Bu takası gözden kaçırmak kolay; çünkü lisans, bir benchmark’ta görünmeyen tek özellik.

Üçü de aynı kategorideki makale çıkarma kütüphanelerine göre belirgin biçimde daha hafif — onlar 21 ile 70 MiB arasında değişiyor. Dönüştürücü, çıkarıcıdan çok daha küçük bir araçtır; bağımlılık bütçenizde bunları ayrı düşünmeye değer.

Bu tabloyu doğru hale getirmeden önce düzeltmem gereken iki karıştırıcı etken

Yukarıdaki sayılar üçüncü sürüm. İlk iki sürüm yanlıştı; bunu özellikle söylemeye değer, çünkü ikisi de kolayca yeniden üretilebiliyor.

Beş örnek yerine dört örnekle kıyaslama. markitdown bu beş dosyanın dördünü çalıştırdı; diğer üç araç beşinin tamamını. Her aracı kendi setinde topladığımda markdownify 98 tablo satırıyla markitdown’ın 36 satırının önüne geçiyordu ve bu, yetenek farkı varmış gibi görünüyordu. Aynı dört örnekte ise sonuç 36’ya 36 — tam beraberlik. Beşinci örnek tablo ağırlıklı olduğu için bu karıştırıcı etki en kötü yönde çalıştı ve yeni araçları mevcut olana karşı neredeyse üç kat şişirdi.

İki sayaç, tek sütun. markitdown’ın yayımlanan md_table_rows değeri, benim okumadığım kendi kodundan geliyordu. Bu sayıyı benimkine karşılaştırmak, iki dönüştürücüyü değil iki sayacı karşılaştırmak anlamına gelebilirdi. Markdown çıktısı diskte saklandığı için çözüm, dört örneğin hepsinde tek bir sayaç çalıştırmaktı — ve bunu yaptığımda markitdown’ın yeniden sayımı, her örnek için yayımlanan değerle tam eşleşti (0, 0, 27, 9). Tanımlar aynıydı; bunu kontrol etmeden bilemezdim.

Bu iki hata da çıktıda görünmezdi. İkisi de güvenle söylenmiş ama yanlış bir tablo üretirdi.

Kim ne kullanmalı?

Bir modele beslemek ya da bu tür sayfalardan yapılandırılmış içerik saklamak mı istiyorsunuz? markdownify ile başlayın. Bu sayaç altında markitdown ile aynı tablo satırı sayısını veriyor, en düşük token kümesinde yer alıyor, MIT lisanslı ve 1.8 MiB kurulum boyutuna sahip. Kendi sayfa tiplerinizde doğruladıktan sonra standartlaştırın.

Bağımlılık bütçesi kilobaytlarla ölçülüyor ve dağıtım yapmıyor musunuz? html2text. Tek paket, 0.2 MiB, tablolar korunuyor. Önce GPL konusunu kontrol edin; son sürümün Nisan 2025’te geldiğini unutmayın.

Zaten bir Node yığınındaysanız? Yanına turndown-plugin-gfm eklenmiş turndown kullanın — ve HTML’i vermeden önce <script> ile <style> öğelerini temizleyin, çünkü turndown bunu yapmaz. Bu iki eksiklik, size fazladan çeyrek token maliyeti ve kaybolmuş tablo yapısı olarak geri döner; ikisi de ancak çıktıya bakınca anlaşılır.

Zaten başka belge formatlarını da dönüştürüyorsanız? markitdown PDF, Office ve daha fazlasını destekliyor; HTML çıktısı da özel dönüştürücülerle yarışacak düzeyde. Tek bağımlılık yerine iki bağımlılık kullanmamak değerli olabilir.

Yönetilen bir API nerede devreye girer?

Bu dört araç da elinizde zaten bulunan HTML’i işler. Hiçbiri sayfa çekmez, JavaScript render etmez, anti-bot katmanını aşmaz — oysa gerçek hedeflerin çoğunda işin zor kısmı tam da budur.

Thunderbit içindeki kendi geliştirici yığınımız bu tarafı kapsıyor. POST /distill bir URL alır ve render ile çekmeyi kendi içinde hallederek temiz, LLM’e hazır Markdown döndürür; POST /extract ise sizin verdiğiniz bir JSON Schema’ya karşı yapay zekâ ile eşleşen yapılandırılmış JSON üretir — yani bambaşka bir çıktı biçimi, sonradan Markdown’dan ayrıştırmanız gerekmeyen satırlar. İkisine de bir MCP sunucusu ve CLI (npx @thunderbit/thunderbit-cli) üzerinden erişilebilir. Fiyatlandırma Thunderbit fiyatlandırma sayfasında.

Dürüst karşılaştırma şu: HTML sizdeyse ve Markdown istiyorsanız, markdownify ücretsizdir ve işi iyi yapar; bu tablo da rakiplerinin hangilerinin aynı işi iyi yaptığını gösteriyor. Eğer sayfaları siz çekiyorsanız ya da düz metin yerine yapılandırılmış satırlar istiyorsanız, bu bambaşka bir satın alma kararıdır.

Daha geniş alan için, web scraping API derlememiz barındırılan seçenekleri; açık kaynak scraper rehberi ise kendi barındırdıklarınızı kapsıyor. Python’da HTML’i Markdown’a dönüştürme pratik anlatımı, llms.txt’nin neyi standartlaştırmaya çalıştığı ise bu kategorinin nereye gittiğini ele alıyor.

Web Verisi Çıkarmak için Thunderbit’i Deneyin

Sonuç

Bu dört örnekli iş yükü için en güçlü varsayılan seçenek markdownify: ortak sayaç altında markitdown ile aynı üretilen tablo satırı sayısı, diğer verimli dönüştürücülere göre %1,3 içinde kalan token sayısı, MIT lisansı ve 1.8 MiB’lık kurulum boyutu.

Popülerlik ile ölçülen davranış arasındaki fark işte asıl bulgu. turndown, tablolara uygun eklentiyi kurmadan yüklenmiş çok sayıda kişinin kullandığı mükemmel bir kütüphane; bunun bedeli ise çeyrek daha fazla token ve artık var olmayan bir tablo yapısı olarak geri dönüyor. Bu iki sayı, siz onları sayana kadar hiçbir yerde görünmüyor.

Tek bir şey alacaksanız şunu alın: çıktısını bir modele emanet etmeden önce dönüştürücünüzün tabloya ne yaptığını kontrol edin. Bu dört aracın üçü makul bir şey yapıyor. En popüler olanı ise, siz özellikle istemediğiniz sürece yapmıyor.

Web Verisi Çıkarmak için Thunderbit’i Deneyin Get Started Free

SSS

Turndown gerçekten tabloları desteklemiyor mu? Çekirdek sürümü desteklemiyor. Tablolar turndown-plugin-gfm adlı ayrı bir paketten geliyor; sıradan npm install turndown bunu içermez. Eklenti olmadan her hücre ayrı paragraf olarak kalır — değerlerin hepsi vardır, fakat satır ve sütun ilişkileri yoktur. Dört örnek boyunca bunun sonucu sıfır Markdown tablo satırı ve aynı içerik için markdownify'den %24,6 daha fazla token oldu.

html2text neden ilk anda tablo yokmuş gibi göründü? Çünkü sayaç mantığım başta ve sonda pipe istiyordu, html2text ise bunları üretmiyor. Team Name | Year | Wins geçerli bir Markdown’dır ve doğru render edilir; sadece | Team Name | Year | biçiminden farklıdır. Düzeltilmiş sayaç, bir ayrıştırıcının yaptığı gibi, ayırıcı satırı olan pipe’lı satır dizisini arar; bu sayede html2text 1 satırdan 32 satıra çıkar. Markdown’ı kendi regex’inizle sonradan işliyorsanız, sizi yakalayacak fark budur.

html2text’teki GPL gerçek bir sorun mu? Yazılımı nasıl birleştirip dağıttığınıza bağlı. GPL-3.0-or-later, MIT’nin getirmediği yükümlülükler doğurabilir; bu yüzden dağıtılacak bir ürün için seçmeden önce lisans sahibini devreye alın. Bu bir uyumluluk kontrolüdür, hukuki tavsiye değil; lisans türü kayıt defteri metadata’sında, depoda ve kurulu paketin METADATA dosyasında doğrulandı.

Bu token sayıları başka sayfalar için de anlamlı mı? %24,6’lık farkın büyük kısmı turndown’ın <script> ve <style> içeriğini bırakmasından geliyor; dolayısıyla fark, sayfanın buna ne kadar sahip olduğuna bağlı olarak değişir — modern bir CMS sayfasında yüksek, statik bir sayfada neredeyse sıfır. Tablolar ise ters yönde etkiliyor: yalnızca tablolardan oluşan örnekte turndown %22 daha ucuz çıktı, çünkü pipe iskeleti üretmiyor. Bayt/token oranı dört araçta da 3.61 ile 3.65 arasında kaldı; yani çıktı yoğunluğu her yerde aynı, fark miktarda. Bu sayı bütçe için önemliyse, kendi korpusunuzu ölçün.

Burada ne test edilmedi? Gerçek dünya çeşitliliği — dört örnek, dört örnektir. İç içe listeler, tanım listeleri, dipnotlar ve matematik ifadeleri. Bozuk HTML; dönüştürücülerin tarihsel olarak en çok ayrıştığı yer burasıdır. Markdown’ı tekrar HTML’e döndürme testi. docling; aynı örnekler diskte mevcut olsa da yayımlanan çalıştırmasında bu alanlar raporlanmadığı için yok sayıldı, tahmin edilmedi. Ve yapılandırma: html2text, varsayılanı 78 olduğu için her satırı sert biçimde bölen body_width=0 ile çalıştırıldı; aksi halde bu tablodaki her karakter ve token sayısı değişirdi.