محول HTML إلى Markdown: حول ترميز الويب الفوضوي إلى نص محمول نظيف

أقوم بترحيل المحتوى لكسب لقمة العيش، بمعنى أن أي شخص قام بتشغيل موقع WordPress لمدة عقد من الزمن يفعل ذلك في النهاية. عندما قمت بنقل مجموعة من المنشورات القديمة من منشئ الصفحات إلى نظام المستندات المستند إلى Markdown، اكتشفت ماذا &quot؛ HTML&quot نظيف؛ يعني حقا في البرية: <p> العلامات ذات الأنماط المضمنة، فارغة <span>s التفاف الكلمات المفردة، <div>s ثلاثة مستويات عميقة حول الفقرة، والعلامة العرضية التي لم يتم إغلاقها أبدًا. لقد أعطاني لصق ذلك في حقل Markdown جدارًا من الأقواس الزاوية الحرفية. نسخ لصق المقدمة فقد النص كل رابط وعنوان وقائمة. لم ينجح أي من الاختصارين، وانتهى بي الأمر بتنظيف المقالات يدويًا لفترة ما بعد الظهر قبل أن أشعر بذلك.

إن الحصول على المعقولية يعني التعامل مع HTML-to-Markdown على حقيقته: تحويل منظم مع مجموعة واضحة من القواعد، وليس نسخ ولصق. يصبح عنصر العنوان # خط. يصبح غامقا **. يصبح الرابط [text](url). يصبح الجدول طاولة أنبوبية. بمجرد حصولك على تلك التعيينات ومحلل تحليلي متسامح بما يكفي للبقاء على قيد الحياة في العلامات الواقعية، يصبح التحويل مملًا وموثوقًا - وهو بالضبط ما تريده. أقوم ببناء [Toolz.dev](/وأضع متصفحًا محول HTML إلى Markdown هناك يطبق هذه القواعد، ولكن هذا الدليل يدور حول القواعد نفسها حتى تفهم الشكل الذي يجب أن يبدو عليه الإخراج ولماذا.

ليرة تركية؛DR: لتحويل HTML إلى Markdown، قم بتعيين عناصر الكتلة إلى مكافئات Markdown الخاصة بها (<h2> → ##، <ul><li> → - ، <blockquote> → > ، <pre><code> → كتلة مسيجة)، خريطة العناصر المضمنة (<strong> → **، <em> → *، <a> → [text](href)، <img> → ![alt](src))، بدوره <table> في جدول أنابيب Markdown بنكهة GitHub، قم بفك تشفير كيانات HTML مرة أخرى إلى أحرف حقيقية، ثم قم بإسقاطها <script>/<style>. استخدم محللًا متسامحًا مع العلامات غير المغلقة، وقم بذلك في المتصفح حتى لا يتم تحميل المحتوى الخاص بك أبدًا.

لماذا تحويل HTML إلى Markdown على الإطلاق؟

Markdown هو التنسيق المحمول لشبكة المطورين الحديثة. ملفات README، ومواقع التوثيق، والمدونات الثابتة (محتوى Hugo، وJekyll، وAstro، وNext.js)، وتطبيقات الملاحظات مثل Obsidian وBear، ومشكلات GitHub، والمطالبات والسياق الذي نغذيه بشكل متزايد لنماذج الذكاء الاصطناعي - جميعها تتحدث Markdown. It&#39؛s نص عادي، يختلف بشكل واضح في Git، ويستمر في الانتقال من نظام إلى آخر دون سحب كومة من علامات العرض التقديمي معه.

وعلى النقيض من ذلك، فإن HTML هو ما أنت عليه ينتهي ب عندما يمر المحتوى عبر متصفح أو محرر WYSIWYG. انسخ قسمًا من صفحة ويب، أو قم بالتصدير من نظام إدارة المحتوى، أو اسحب نص المقالة من واجهة برمجة التطبيقات، أو احصل على نص منسق من حقل نص غني، وستحصل على HTML - عادةً ما يكون HTML مزدحمًا، ومليئًا بعناصر الغلاف والأنماط المضمنة التي لا تريدها &#39؛ تريد في مستند نظيف. التحويل هو الجسر من &quot؛ المحتوى المحاصر في ترميز العرض التقديمي واقتباسه؛ إلى &quot؛ المحتوى يمكنني إصداره وتحريره وإعادة نشره في أي مكان.&quot؛

تتكرر السيناريوهات باستمرار بمجرد ملاحظتها. ترحيل مدونة من WordPress أو Medium. سحب الوثائق من نظام مساعدة HTML القديم. تحويل المقالة التي تم كشطها إلى ملاحظة تخفيض السعر. تحويل رسالة إخبارية عبر البريد الإلكتروني و#39؛s HTML إلى مسودة تخفيض السعر. تغذية صفحة ويب و#39؛s المحتوى إلى LLM كسياق نظيف بدلاً من HTML الخام الذي يهدر الرموز المميزة عليه <div> حساء. في كل حالة، تكون البدائل اليدوية - إعادة كتابة النص أو نسخه ولصقه وإعادة بناء التنسيق يدويًا - بطيئة وخاسرة. المحول القائم على القواعد ليس كذلك.

كيف يتم تعيين HTML إلى Markdown؟

ينقسم التعيين بشكل طبيعي إلى طبقتين: البنية على مستوى الكتلة والتنسيق المضمن.

عناصر الكتلة حدد الهيكل العظمي للمستند &#39؛، ولكل منها نظير مباشر لـ Markdown

• <h1>.ح<h6> يصبح # خلال ###### خطوط العنوان.
• <p> تصبح فقرة مفصولة بأسطر فارغة.
• <ul>/<li> يصبح - قوائم نقطية؛ <ol>/<li> يصبح 1. قوائم مرقمة، وقوائم متداخلة مسافة بادئة بمسافتين.
• <blockquote> البادئات كل سطر مع > .
• <hr> يصبح ---.
• <pre><code> تصبح كتلة رمز مسيجة ذات علامات خلفية ثلاثية.
• <table> تصبح طاولة أنابيب Markdown بنكهة GitHub.

العناصر المضمنة تزيين النص داخل تلك الكتل:

• <strong> و <b> يصبح **bold**.
• <em> و <i> يصبح *italic*.
• <code> يصبح `inline code`.
• <a href="..."> يصبح [link text](href)، الحفاظ على title السمة عند وجودها.
• <img> يصبح ![alt text](src).
• <del> و <s> يصبح ~~strikethrough~~ (امتداد Markdown بنكهة GitHub).
• <br> يصبح كسرًا للخط الصلب - مسافتين خلفيتين قبل الخط الجديد.

قم بتشغيل هذه القواعد على كتلة حقيقية من HTML وستظل البنية سليمة. نظرا لهذا الإدخال:

<article>
  <h1>Getting Started</h1>
  <p>Convert <strong>HTML</strong> into clean <em>Markdown</em>.</p>
  <ul>
    <li>Paste from a CMS</li>
    <li>Get portable output</li>
  </ul>
  <pre><code class="language-js">const md = convert(html)</code></pre>
</article>

تحصل على:

# Getting Started

Convert **HTML** into clean *Markdown*.

- Paste from a CMS
- Get portable output

```js
const md = convert(html)
```

هناك تفصيلان في هذا الإخراج يستحقان النداء. أولا، ال <article> لم يساهم الغلاف بأي شيء - مثل الحاويات الهيكلية <article>، <section>، و <div> شفافة؛ يتكرر المحول فيها ويجعل أطفالها كتلًا. ثانيا، تم التقاط سياج الكود js كلغة لها. هذا &#39؛s لأن <code> العنصر محمول class="language-js"، يتم استخدام أدوات تمييز بناء الجملة التقليدية، ويقرأ المحول الجيد تلك الفئة لتسمية السياج. It&#39؛s شيء صغير يُحدث فرقًا بين كتلة التعليمات البرمجية التي يتم تمييزها على موقع المستندات الخاصة بك وتلك التي لا تحتوي على &#39؛t.

ما الذي يجعل المحول ينجو من HTML في العالم الحقيقي؟

القواعد المذكورة أعلاه هي الجزء السهل. السبب وراء فشل محولات regex الملفوفة يدويًا - وI&#39؛ لقد كتبت ورُفضت زوجين - هو أن HTML الحقيقي يكسر الافتراضات باستمرار. تظهر ثلاث مشاكل مرارا وتكرارا.

العلامات غير المغلقة. المتصفحات مشهورة بالتسامح: <p>one<p>two يتم تقديمه كفقرتين لأن أ <p> يُغلق ضمنيًا عند فتح عنصر كتلة آخر، و <li>a<li>b هل هناك عنصران في القائمة لنفس السبب. محلل ساذج يغلق العناصر فقط على الصريح </p> سوف تتداخل الفقرة الثانية داخل الفقرة الأولى وتشوه كل شيء في اتجاه مجرى النهر. يطبق المحول القوي نفس قواعد العلامة النهائية الضمنية التي تحددها مواصفات HTML: يؤدي فتح عنصر على مستوى الكتلة إلى إغلاق فقرة مفتوحة؛ فتح أ <li> يغلق السابق. يقوم المحول الخاص بي بذلك، ولهذا السبب عادةً ما يعمل لصق مخرجات CMS غير الدقيقة.

<script> و <style> كتل. تحتوي هذه على التعليمات البرمجية وCSS، وليس المحتوى، ويجب أن تؤخذ محتوياتها حرفيًا (أ < داخل JavaScript ليست علامة) ثم يتم إسقاطها بالكامل. انسَ حالتها الخاصة وستحصل على مصدر JavaScript ينزف في Markdown الخاص بك.

كيانات HTML. محتوى الويب مليء &، ©، —،  ، والمراجع الرقمية مثل ’. في Markdown - وهو نص عادي - تريد الأحرف الفعلية: &، ©، —وفاصلة عليا حقيقية. فك تشفير الكيانات المسماة والرقمية ليس اختياريًا؛ تخطيه وسيقرأ Markdown النظيف الخاص بك مثل مصدر العرض.

ولهذا السبب توقفت عن محاولة تحويل HTML باستخدام البحث والاستبدال وقمت ببناء محلل متسامح مناسب بدلاً من ذلك. فهو يقوم بترميز HTML إلى شجرة - يتعامل مع التعليقات والعناصر الفارغة مثل <br> و <img>أسماء العلامات الكبيرة والسمات غير المقتبسة - ثم قم بالتجول في تلك الشجرة التي تنبعث منها Markdown. والجدير بالذكر أنه لا &#39؛ يعتمد على المتصفح &#39؛s DOM، مما يعني أن نفس المنطق يعمل على الخادم أيضًا، ولكن المردود العملي بالنسبة لك بسيط: إنه لا &#39؛ لا يرمي العلامات الفوضوية التي تتكون منها مواقع الويب الحقيقية.

كيف أستخدم المحول؟

على Toolz.dev/tools/html-to-markdown، الصق HTML الخاص بك في الجزء الأيسر وسيظهر Markdown على اليمين أثناء الكتابة - هناك &#39؛ لا يوجد تحميل ولا زر تحويل للبحث عنه. قم بتحميل العينة إذا كنت تريد رؤية كل بنية مدعومة في وقت واحد.

تغطي بعض الخيارات التفضيلات الشائعة. اختر شخصيتك النقطية (-، *، أو +) للقوائم غير المرتبة لتتناسب مع نمط مشروعك &#39؛s. احتفظ بـ GitHub Flavored Markdown للطاولات والإضراب، أو إيقاف تشغيله إذا كان هدفك يقبل CommonMark فقط. تبديل & اقتباس؛ احتفظ بالروابط والاقتباس؛ إيقاف التشغيل عندما تريد النثر ولكن ليس عناوين URL - وهو أمر مفيد لتحويل مقالة ذات رابط ثقيل إلى نص قراءة نظيف - و&quot؛ احتفظ بالصور والاقتباس؛ قم بتجريد الصور بالكامل. يعرض صف الإحصائيات الكلمات والعناوين والروابط والصور وكتل التعليمات البرمجية ووقت القراءة المقدر، وهو عبارة عن فحص سريع للعقل الذي صادفته البنية قبل لصق النتيجة في مكان ما.

كما هو الحال مع كل شيء على الموقع، يكون التحويل من جانب العميل بنسبة 100%. المحلل اللغوي هو JavaScript عادي يعمل في متصفحك، لذلك لا يتم إرسال الصفحات الملصقة والوثائق الداخلية والمسودات غير المنشورة إلى أي مكان أبدًا. That&#39؛s هو الإعداد الافتراضي الصحيح لعمل المحتوى - يجب عليك &#39؛ يجب عليك تحميل مسودة إلى خادم &#39؛s فقط لإعادة تنسيقه - وهذا يعني أن الأداة تستمر في العمل دون اتصال بالإنترنت. أتعمق في سبب أهمية المعالجة من جانب المتصفح في دليل أدوات خصوصية البيانات.

HTML مقابل Markdown: متى يتم استخدام أي منها

التحويل بينهما سهل؛ معرفة ما تريد هو القرار الحقيقي.

جانب	HTML	تخفيض السعر
الغرض الأساسي	العرض في المتصفح	كتابة وتخزين النص
سهولة القراءة كمصدر	فقير (ثقيل)	ممتاز (يقرأ كنص عادي)
فرق جيت	صاخب	نظيف
قابلية النقل عبر الأنظمة	منخفض	عالي
التحكم الدقيق في التخطيط	ممتلئ	محدودة حسب التصميم
حيث يعيش	صفحات الويب، إخراج WYSIWYG	READMEs، المستندات، الملاحظات، المواقع الثابتة
منحنى التعلم	حاد	دقائق

يتداول Markdown التحكم في التخطيط عمدًا من أجل البساطة، ولهذا السبب يفوز بالمحتوى الذي تكتبه وتصدره وتتحرك فيه، ويخسر عندما تحتاج إلى عرض تقديمي على مستوى البكسل. تحويل HTML إلى Markdown عندما تقوم أنت &#39؛ بإعادة الالتقاط أو الترحيل محتوى؛ احتفظ بـ HTML عندما تقوم &#39؛ بإعادة بناء أ صفحة. وعندما تحتاج إلى السير في الاتجاه الآخر - تخفيض التصنيف إلى HTML لحقل CMS أو قالب البريد الإلكتروني - فإن تخفيض السعر إلى محول HTML هي صورة معكوسة لهذه الأداة وتشترك في نفس الاصطلاحات، لذا فإن رحلتين ذهابًا وإيابًا بشكل نظيف للهياكل المشتركة.

حيث يتناسب هذا مع سير عمل المحتوى

نادرًا ما يكون تحويل التنسيق هو المهمة بأكملها؛ it&#39؛s خطوة واحدة. بعد أن أقوم بتحويل مقال إلى Markdown I&#39؛ عادةً ما أقوم بتشغيل النص من خلال ملف عداد الكلمات للتحقق من الطول مقابل الهدف، وإذا كان المصدر يحتوي على كيانات HTML تحتاج إلى التشفير مرة أخرى لوجهة أخرى، فإن برنامج تشفير/فك تشفير كيان HTML يعالج العكس. عندما I&#39؛ أقوم بتنظيف HTML المكتوب بخط اليد قبل التحويل، أ مصغر HTML يجرد الضوضاء أولا. تترابط هذه الأدوات الصغيرة معًا في خط أنابيب قابل للتكرار، وهي الفكرة الكاملة وراء كيفية تفكيري في مجموعة الأدوات القائمة على المتصفح - لقد وضعت هذه الفلسفة في دليل مجموعة أدوات مطور الويب والأوسع دليل أدوات الترميز.

الأخطاء الشائعة في تحويل HTML إلى Markdown

نسخ ولصق النص المعروض بدلاً من تحويل HTML. تفقد الروابط والعناوين والقوائم - كل البنية. تحويل العلامات الفعلية.

تجاهل فئة لغة الكود. إذا خرجت الكتل المسيجة الخاصة بك بدون لغة وتم تسليط الضوء على don&#39؛t، فقد أسقط المحول class="language-x" تلميح. واحد جيد يقرأه.

بافتراض أن CommonMark وGFM متماثلان. الجداول والإشارات هي امتدادات GitHub Flavored Markdown، وليست CommonMark الأساسية. إذا كانت وجهتك هي CommonMark الصارمة، فسيتم الفوز بالجدول &#39؛t - التحويل مع إيقاف تشغيل GFM والتعامل مع الطاولات بطريقة أخرى.

الثقة في المحول الذي يقوم بتحميل المحتوى الخاص بك. الكثير من &quot؛ مجاني وquot؛ المحولات عبر الإنترنت انشر HTML الخاص بك على الخادم. بالنسبة لأي شيء غير منشور أو داخلي، هذا &#39؛s تسرب. استخدم أداة من جانب العميل.

أسئلة وأجوبة

كيف يمكنني تحويل HTML إلى Markdown؟

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

هل يتعامل المحول مع الجداول؟

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

ماذا يحدث للروابط والصور؟

تصبح المراسي [نص الرابط](href) وتصبح الصور ![alt text](src)، مع الحفاظ على سمة العنوان عند وجودها. إذا قمت بإيقاف تشغيل &quot؛ احتفظ بالروابط والاقتباس؛ يتم الاحتفاظ بالنص الأساسي ولكن يتم إسقاط عنوان URL، ويتم إيقاف تشغيله &quot؛ احتفظ بالصور والاقتباس؛ يزيل الصور بالكامل - وهو مفيد عندما تريد النثر فقط.

هل كتل الكود والرمز المضمن محفوظة؟

نعم. أ

 block becomes a fenced code block, and if the code element carries a class like "language-js" that language is added to the fence. Inline  spans are wrapped in backticks, and the code text itself is never escaped or reformatted, so snippets stay exactly as written.

Will it work on messy HTML copied from a website?
That is what it is built for. The parser is tolerant of unclosed tags, uppercase element names, unquoted attributes and stray comments, and it strips