أكثر مكتبة HTML إلى Markdown شهرة لا تحوّل الجداول

كان turndown الأكثر حصولًا على النجوم بين المكتبات الأربع التي تم اختبارها عند لقطة البيانات الوصفية، إذ يمتلك 11,386 نجمة على GitHub. وعلى ملفات HTML الأربعة المشتركة، أخرج صفر جداول Markdown بالإعدادات الافتراضية الأساسية، واستخدم عددًا من الرموز أعلى بنسبة 24.6% من markdownify لنفس المدخلات.

نجحت جميع المكتبات الأربع في استرجاع كل مؤشرات المحتوى. الفارق كله يكمن في ما يحدث للبنية، وما الذي تكلفك إياه هذه البنية لاحقًا.

ما الذي تم قياسه، وعلى أي ملفات

كانت هذه القاعدة البحثية تحتوي بالفعل على حزمة خاصة بـ markitdown تضم خمسة ملفات HTML وسلاسل فحص محددة مسبقًا — نصوص دقيقة يُتحقق من بقائها، إضافة إلى سلاسل boilerplate لاكتشاف العناصر الزخرفية في الصفحة. وتعتمد المقارنة الإجمالية على الملفات الأربعة المشتركة بين المحوّلات الأربعة: كتالوج متجر كتب، وموقع اقتباسات، وجدول إحصائيات هوكي، ومقال ويكيبيديا عن استخراج البيانات من الويب. أما الملف الخامس، Nothing but tables، فيُستخدم فقط كاختبار تشخيصي كثيف بالجداول، ولا يدخل ضمن إجمالي 24.6%.

المحوّلات الأربعة هي: turndown الإصدار 7.2.4 (Node)، وmarkdownify الإصدار 1.2.3، وhtml2text الإصدار 2025.4.15، وmarkitdown، مع استخدام صفوفه المنشورة كما هي. الصفحات: كتالوج متجر كتب، وموقع اقتباسات، وجدول إحصائيات هوكي، ومقال ويكيبيديا عن استخراج البيانات من الويب.

كل اسم مقياس أدناه يطابق حقل العلامة الخاصة بـ markitdown حرفيًا، لذلك يمكن وضع الصفوف جنبًا إلى جنب من دون الحاجة إلى التوفيق بين تعريفين مختلفين للكلمة نفسها.

الجدول

أربعة ملفات — وهي نفسها التي شغّلها markitdown أيضًا. الأرقام الكاملة لكل ملف موجودة في fiveway-scores.json. تم عدّ الرموز باستخدام o200k_base؛ وأُعيد عدّ صفوف جداول markitdown من Markdown المخزن لديه نفسه، باستخدام العدّاد ذاته المستخدم مع البقية.

بقاء المحتوى متعادل. نجت جميع مؤشرات النص الستة عشر عبر الملفات الأربعة مع كل محوِّل. إذا كان سؤالك الوحيد هو "هل سيمر النص؟" فالإجابة هنا نعم مع أي من هذه المكتبات الأربع.

البنية ليست متعادلة. في الملفات الأربعة المشتركة، يخرج كل من markdownify وmarkitdown 36 صفًا في جداول Markdown؛ ويخرج html2text 32 صفًا؛ بينما لا يخرج turndown أي صف. وفي الاختبار المنفصل المخصص للجداول فقط، أخرج markdownify 62 صفًا وhtml2text 59؛ وهذه الصفوف غير محسوبة في الإجمالي أعلاه.

تكلفة الرموز أعلى بنسبة 24.6% مع turndown، والسبب ليس الجداول. كنت أعتقد أنه كذلك، لكن الأرقام حسب كل ملف تقول غير ذلك — كما ستجد أدناه.

ماذا يفعل turndown بالجدول

فيما يلي ملف إحصائيات الهوكي نفسه، بالصفوف ذاتها، بثلاث صيغ.

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  | ...

كل قيمة تبقى موجودة بعد تحويل turndown، ولهذا حصل على 16/16 في مؤشرات الفحص. لكن ما لا يبقى هو أي عمود تنتمي إليه كل قيمة. اقرأ مخرجات turndown وستجد أن 44 مجرد رقم في سطر؛ لا يمكنك استنتاج أنه عدد انتصارات بوسطن من دون عدّ المواضع وافتراض أن أي خلية لم تكن فارغة. وفي هذا الملف، بعض الخلايا فارغة بالفعل، لذا حتى هذا العدّ لا يصلح.

وبالنسبة لنموذج يقرأ الناتج، فهذا هو الفرق بين جدول يمكنه الإجابة عنه وبين قائمة أرقام سيضطر إلى التخمين بشأنها.

هذا ليس خللًا بقدر ما هو حدّ موثّق — فاللبّ الأساسي في turndown لا يعالج الجداول، وturndown-plugin-gfm موجود لإضافتها. لكن التثبيت الافتراضي لا يضم هذا الإضافة، و11,386 نجمة توحي بأن كثيرين يستخدمون الإعداد الافتراضي.

من أين تأتي فجوة الرموز فعلًا

كتبت الفقرة السابقة وأنا أظن أن فجوة الرموز البالغة 24.6% سببها تحوّل الجداول إلى نص مسطّح. ثم راجعت الأرقام لكل ملف، واتضح أن هذا ليس السبب.

في الملف الذي هو مجرد جداول، يكون turndown أقل تكلفة بنسبة 22% — لأن هياكل الأنابيب | تستهلك رموزًا أيضًا، وturndown لا ينتج شيئًا منها. إذًا تسطيح الجدول بحد ذاته ليس عقوبة على الرموز.

ملف ويكيبيديا يمثل 74% من الإجمالي، ويحتوي على تسعة صفوف جدول. والفجوة البالغة 15,378 حرفًا لا يمكن أن تكون بسبب الجداول. بل بسبب هذا:

(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> و<style>، بينما markdownify وhtml2text يفعلان ذلك. وعند العدّ عبر العلامات التي تظهر داخل تلك العناصر فقط: مخرجات turndown تحمل 10 علامات script و84 علامة style عبر الملفات، بينما لا يحمل الاثنان الآخران أيًا منها. وفي صفحة ويكيبيديا، تتسبب ثمانية أسطر من إعدادات JavaScript وCSS المضمّنة في MediaWiki في 14,644 حرفًا — أي 95% من إجمالي الفجوة (script-style-stripping.json).

هذه هي النتيجة التي كنت سأتصرف بناءً عليها فعلًا. الجدول المسطح مشكلة بنيوية تراها بعينك. أما كتلة إعدادات JavaScript داخل Markdown فهي تكلفة صافية بلا أي فائدة معلوماتية، وعلى صفحة حقيقية تتجاوز أثر كل شيء آخر في هذه المقارنة.

html2text يكتب جداول قد لا تتعرف عليها

سجّل html2text 32 صفًا مقابل 36 لكل من markdownify وmarkitdown، بينما حسبته النسخة الأولى من العدّاد على أنه 1 فقط.

الخطأ كان في قاعدة العدّ التي وضعتها أنا، لا في المكتبة. فـ html2text يخرج Team Name | Year | Wins من دون أنابيب في البداية والنهاية — وهو شكل شائع من جداول Markdown، لكنه لا يظهر للتعبير النمطي الذي يتطلب ^\|.*\|$. كنت قد كتبت هذا التعبير، وشغلته، وكنت على وشك أن أصرّح بأن html2text لا يدعم الجداول.

لكنه يدعمها. النسخة المصححة من العدّاد تستخدم أسلوبًا استدلاليًا: سلسلة من الأسطر المتتالية التي تحتوي على أنابيب، مع سطر فاصل داخلها. بهذه القاعدة، ينتقل html2text من 1 إلى 32. وهذا ليس محلل Markdown كاملًا، لذا يجب قراءة إجمالي الصفوف بوصفها قياسات وفق عدّاد موثّق، لا نتائج عرض عالمية.

ومن المفيد معرفة هذا إذا كنت ستعالج Markdown لاحقًا بتعبيراتك النمطية الخاصة: اثنتان من هذه المكتبات الأربع تخرجان أنابيب خارجية، وواحدة لا تفعل ذلك.

الترخيص الذي لا يذكره أحد

install-and-import.json. جرى تثبيت كل مكتبة في بيئة فارغة منفصلة. وتم تأكيد التراخيص من ثلاثة مصادر: بيانات السجل، ومستودع GitHub، وملف METADATA الخاص بالحزمة المثبتة، الذي يذكر: License-Expression: GPL-3.0-or-later.

أخف مكتبة في هذا القياس — حزمة واحدة، 0.2 MiB — مرخّصة بـ GPL-3.0-or-later. وما إذا كان ذلك يؤثر في مشروعك يعتمد على كيفية دمج البرنامج وتوزيعه. اعتبره نقطة مراجعة للشخص المسؤول عن الترخيص؛ فهذه المقالة ليست استشارة قانونية. ويظهر markitdown هنا على أنه غير مقاس لأن التثبيت والترخيص لم يُلتقطا في هذا الأصل المحدد.

من السهل تفويت هذه المقايضة لأن الترخيص هو الخاصية الوحيدة التي لا تظهر في أي benchmark.

وجميعها أخف بكثير من مكتبات استخراج المقالات ضمن الفئة نفسها — إذ تتراوح تلك بين 21 و70 MiB. فالمحوِّل شيء أصغر بكثير من أداة الاستخراج، ومن المفيد فصلهما عند التخطيط لميزانية الاعتماديات.

تعارضتان اضطررت إلى تصحيحهما قبل أن يصبح هذا الجدول صحيحًا

الأرقام أعلاه هي النسخة الثالثة. أما النسختان الأولى والثانية فكانتا خاطئتين بطريقة تستحق الذكر، لأن كليهما سهل الإعادة.

خمسة ملفات مقابل أربعة. شغّل markitdown أربعةً من هذه الملفات الخمسة؛ بينما شغّلت المكتبات الثلاث الأخرى الملفات الخمسة كلها. وعند جمع نتائج كل أداة على مجموعتها الخاصة، بدا markdownify وكأنه ينتج 98 صفًا في الجداول مقابل 36 لـ markitdown، وأوهم ذلك بوجود فجوة في القدرة. لكن على الأربعة نفسها تصبح النتيجة 36 مقابل 36 — تعادل تام. والملف الخامس هو الملف الأكثر امتلاءً بالجداول، لذلك جرى هذا الالتباس في أسوأ اتجاه ممكن، إذ ضخّم المبتدئ مقارنةً بالمخضرم بما يقارب ثلاثة أضعاف.

عدادان، عمود واحد. كانت قيمة md_table_rows المنشورة لدى markitdown ناتجة من كوده الخاص، الذي لم أكن قد قرأته. ومقارنة هذا الرقم بعدّادي قد تعني مقارنة عدّادين مختلفين بدل مقارنة محوّلين. أما مخرجاته Markdown فمخزنة على القرص، لذا كان الحل هو تشغيل عداد واحد على الأربعة كلها — وعندما فعلت ذلك، خرجت إعادة عدّ markitdown مساوية تمامًا للرقم المنشور لكل ملف (0، 0، 27، 9). التعريفات كانت متفقة؛ لم أكن لأعرف ذلك من دون التحقق.

ولا كان أيٌّ من الخطأين سيظهر في المخرجات. وكلاهما كان سيؤدي إلى جدول واثق لكنه خاطئ.

من يجب أن يستخدم ماذا

هل تغذّي نموذجًا، أو تخزن محتوىً بنيويًا من صفحات كهذه؟ ابدأ بـ markdownify. فهو يتعادل مع markitdown في عدد صفوف الجداول الناتجة وفق هذا العدّاد، ويقع ضمن أقل مجموعة من حيث الرموز، وترخيصه MIT، ويُثبَّت بحجم 1.8 MiB. اختبره على أشكال صفحاتك الخاصة قبل اعتماده بشكل قياسي.

ميزانيتك بالكيلوبايت، ولا تقوم بإعادة التوزيع؟ اختر html2text. حزمة واحدة، 0.2 MiB، مع بقاء الجداول سليمة. تحقّق أولًا من مسألة GPL، ولاحظ أن آخر إصدار كان في أبريل 2025.

تعمل أصلًا ضمن بيئة Node؟ استخدم turndown مع تثبيت turndown-plugin-gfm بجانبه — واحذف <script> و<style> من HTML قبل تمريره إليه، لأن turndown لن يفعل ذلك. هذان الإغفالات وحدهما يكلّفانك ربع الرموز الإضافية وبنية الجدول نفسها، ولن تلاحظ ذلك إلا عندما تفحص الناتج.

تحوّل بالفعل صيغ مستندات أخرى؟ يتعامل markitdown مع PDF وOffice وغيرهما، ومخرجاته من HTML تنافس المحوّلات المتخصصة. وجود اعتماد واحد بدل اثنين أمر له قيمته.

أين تناسب الواجهة المُدارة

جميع هذه الأدوات الأربع تتعامل مع HTML الموجود لديك أصلًا. ولا واحدة منها تجلب صفحة، أو تُشغّل JavaScript، أو تتجاوز طبقة anti-bot — وفي كثير من الأهداف الواقعية، هذا هو الجزء الأصعب.

تغطّي منصتنا للمطورين في Thunderbit هذا الجانب. POST /distill يستقبل عنوان URL ويعيد Markdown نظيفًا جاهزًا لـ LLM مع معالجة التحميل والتنفيذ؛ بينما POST /extract يعيد JSON بنيويًا مطابقًا لـ AI schema بناءً على JSON Schema تقدمه أنت، وهو شكل إخراج مختلف تمامًا — صفوف منظمة بدل جدول Markdown ستضطر لاحقًا إلى تحليله. وكلاهما متاح عبر خادم MCP وواجهة CLI (npx @thunderbit/thunderbit-cli). الأسعار موجودة في صفحة تسعير Thunderbit.

المقارنة الصادقة: إذا كان HTML لديك جاهزًا وتريد Markdown، فإن markdownify مجاني ويؤدي المهمة جيدًا، وهذا الجدول يبيّن أيًّا من منافسيه يفعل الشيء نفسه. أما إذا كنت تجلب الصفحات أو تريد صفوفًا بنيوية بدل النص النثري، فهذه عملية شراء مختلفة.

وللحصول على صورة أوسع، يغطي استعراض واجهات web scraping APIs الخيارات المستضافة، كما يغطي المرجع الأساسي لأدوات الاستخراج مفتوحة المصدر الأدوات المستضافة ذاتيًا. أما تحويل HTML إلى Markdown في Python فهو الشرح العملي، وما الذي يحاول llms.txt توحيده يوضح إلى أين يتجه هذا المجال كله.

جرّب Thunderbit لاستخراج بيانات الويب

الخلاصة

في هذا الحمل المكوَّن من أربعة ملفات، يكون markdownify هو الخيار الافتراضي الأقوى: نفس عدد صفوف الجداول الناتجة مثل markitdown تحت العدّاد المشترك، وعدد رموز يقع ضمن 1.3% فقط من المحوّلات الفعالة الأخرى، وترخيص MIT، وحجم تثبيت يبلغ 1.8 MiB.

هذه الفجوة بين الشعبية والسلوك المقاس هي جوهر النتيجة. turndown مكتبة ممتازة، لكن كثيرين ثبتوها من دون الإضافة التي تمكّنها من التعامل مع الجداول، وتظهر تكلفة ذلك في شكل 24.6% رموز إضافية وبنية جدول لم تعد موجودة. ولا يظهر أيٌّ من الرقمين في أي مكان حتى تقوم بعدّهما.

إذا أخذت شيئًا واحدًا من هذا: افحص ما يفعله المحوّل بالجدول قبل أن تثق بمخرجاته أمام نموذج. ثلاثة من هذه الأربعة تفعل شيئًا معقولًا. الأكثر شهرة لا يفعل، إلا إذا طلبت منه ذلك.

جرّب Thunderbit لاستخراج بيانات الويب Get Started Free

الأسئلة الشائعة

هل turndown لا يدعم الجداول فعلًا؟ نعم، اللبّ الأساسي لا يدعمها. الجداول تأتي من turndown-plugin-gfm، وهي حزمة منفصلة، والتثبيت البسيط عبر npm install turndown لا يتضمنها. من دون الإضافة، تبقى كل خلية كأنها فقرة مستقلة — القيم موجودة كلها، لكن علاقة الصفوف والأعمدة ليست موجودة. وعلى أربع ملفات، أدى ذلك إلى صفر صفوف Markdown مع جداول و24.6% رموز أكثر من markdownify لنفس المحتوى.

لماذا بدا html2text كأنه بلا جداول في البداية؟ لأن عدّادي كان يتطلب أنابيب في البداية والنهاية، بينما html2text لا يخرجهما. Team Name | Year | Wins صياغة Markdown صحيحة وتُعرض بشكل سليم؛ إنها ببساطة أسلوب مختلف عن | Team Name | Year |. العدّاد المصحح يبحث عن سلسلة من الأسطر التي تحتوي على أنابيب مع سطر فاصل، بالطريقة التي يتبعها المحلل، وعندها ينتقل html2text من 1 صف إلى 32. وإذا كنت تعالج Markdown لاحقًا بتعابيرك النمطية الخاصة، فهذه هي الفجوة التي ستوقعك.

هل مشكلة GPL في html2text حقيقية؟ يعتمد ذلك على كيفية دمج البرنامج وتوزيعه. قد تفرض GPL-3.0-or-later التزامات لا يفرضها MIT، لذا يجب إشراك الجهة المسؤولة عن الترخيص قبل اختياره لمنتج موزع. هذه نقطة امتثال وليست استشارة قانونية؛ وقد تم التأكد من هوية الترخيص عبر بيانات السجل والمستودع وملف METADATA الخاص بالحزمة المثبتة.

هل هذه الأرقام الخاصة بالرموز ذات معنى لصفحات أخرى؟ فجوة 24.6% سببها في الغالب احتفاظ turndown بمحتوى <script> و<style>، لذا فهي تكبر كلما زاد وجود هذا المحتوى في الصفحة — وتكون كبيرة في صفحات CMS الحديثة، وقريبة من الصفر في الصفحات الثابتة. أما الجداول فتدفعها في الاتجاه الآخر: ففي الملف الذي كان كله جداول، كان turndown أقل تكلفة بنسبة 22% لأنه لا ينتج هياكل الأنابيب. وكانت كثافة البايتات لكل رمز بين 3.61 و3.65 لجميع الأدوات الأربع، لذا فالكثافة في المخرجات متشابهة، والاختلاف في الكمية. قِس على مجموعتك الخاصة إذا كانت الأرقام مهمة لميزانيتك.

ما الذي لم يتم اختباره هنا؟ التنوع الواقعي — أربعة ملفات ليست العالم كله. القوائم المتداخلة، وقوائم التعريف، والحواشي، والرياضيات. وHTML غير المنضبط، وهو الموضع الذي تختلف فيه المحوّلات تاريخيًا أكثر من غيره. وإعادة تحويل Markdown إلى HTML. وdocling، إذ لديه الملفات نفسها على القرص لكن تشغيله المنشور لا يورد هذه الحقول، لذلك غاب بدل أن يُقدَّر. وكذلك الإعدادات: شُغّل html2text مع body_width=0 لأن القيمة الافتراضية 78 تُلزم كل سطر بلفٍّ قاسٍ، وهو ما كان سيغيّر كل حرف وكل عدد من الرموز في هذا الجدول.