محوّل HTML إلى Markdown

ما هو تحويل HTML إلى Markdown؟

يحوّل تحويل HTML إلى Markdown ترميزَ HTML إلى Markdown، وهي صياغة تنسيق نصية خفيفة الوزن أنشأها John Gruber عام 2004. صُممت Markdown لتكون مقروءة دون الحاجة إلى عرض مُصيَّر. فبينما يتطلب HTML وسوم فتح وإغلاق كـ<strong> و<a href="">، تستخدم Markdown رموزاً مختصرة: **نص عريض**، و[روابط](url)، و# عناوين. يُنتج تحويل HTML إلى Markdown ملفات أسهل قراءةً وتحريراً وإدارةً في أنظمة التحكم بالإصدارات مقارنةً بـHTML الخام.

تُحوِّل عملية التحويل عناصر HTML إلى مقابلاتها في Markdown. فيصبح <h2> عبارةً عن ##، ويتحول <ul><li> إلى - عنصر، ويصبح وسم <a> صياغة [نص](url). بعض عناصر HTML لا يوجد لها مقابل مباشر في Markdown، كـ<div> و<span> وسمات البيانات المخصصة. تحذف أدوات التحويل عادةً هذه الوسوم أو تمررها كـHTML خام وفق الإعدادات.

أصبحت Markdown الصيغة المعيارية للكتابة في توثيق المطورين (GitHub وGitLab وBitbucket)، ومولدات المواقع الثابتة (Hugo وJekyll وAstro)، وتطبيقات تدوين الملاحظات (Obsidian وNotion)، والمدونات التقنية. يُعدّ تحويل محتوى HTML الموجود إلى Markdown خطوةً شائعة عند ترحيل المواقع، أو استيراد محتوى من أنظمة إدارة المحتوى، أو أرشفة صفحات الويب بصيغة محمولة. وعلى عكس HTML، تُنتج ملفات Markdown فروقاً نظيفة في أنظمة التحكم بالإصدارات، مما يجعل مراجعة تغييرات التوثيق أمراً عملياً.

لماذا تستخدم محوّل HTML إلى Markdown؟

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

حالات استخدام محوّل HTML إلى Markdown

مرجع عناصر HTML إلى Markdown

يوضح الجدول أدناه كيفية تعيين عناصر HTML الشائعة إلى مقابلاتها في Markdown. يتبع هذا التعيين اصطلاحات GitHub-Flavored Markdown (GFM)، التي توسّع مواصفات CommonMark بإضافة الجداول والشطب وقوائم المهام. العناصر غير المدرجة هنا (كـ<div> و<form> ومكونات الويب المخصصة) لا يوجد لها مقابل في Markdown وإما تُحذف أو تُمرَّر كـHTML خام.

نكهات Markdown: GFM مقابل CommonMark مقابل الأصلية

ليست جميع صيغ Markdown متطابقة. تهم صيغة المخرج لأن منصات مختلفة تُحلّل Markdown بطرق مختلفة. النكهات الثلاث الأكثر شيوعاً هي GitHub-Flavored Markdown (GFM) وCommonMark وMarkdown الأصلية لـGruber.

أمثلة برمجية

أمثلة عملية بـJavaScript (Turndown) وPython (markdownify وhtml2text) وGo وPandoc في سطر الأوامر.

import TurndownService from 'turndown'

const turndown = new TurndownService({ headingStyle: 'atx' })
const html = '<h1>Title</h1><p>A <strong>bold</strong> paragraph.</p>'
const md = turndown.turndown(html)
console.log(md)
// → "# Title\n\nA **bold** paragraph."

from markdownify import markdownify

html = '<h2>Section</h2><ul><li>First</li><li>Second</li></ul>'
md = markdownify(html, heading_style='ATX')
print(md)
# → "## Section\n\n- First\n- Second"

import html2text

converter = html2text.HTML2Text()
converter.body_width = 0  # disable line wrapping

html = '<p>Visit <a href="https://example.com">Example</a> for details.</p>'
md = converter.handle(html)
print(md)
# → "Visit [Example](https://example.com) for details."

package main

import (
	"fmt"
	md "github.com/JohannesKaufmann/html-to-markdown"
)

func main() {
	converter := md.NewConverter("", true, nil)
	html := `<h3>Go Example</h3><p>Code: <code>fmt.Println()</code></p>`
	markdown, _ := converter.ConvertString(html)
	fmt.Println(markdown)
	// → "### Go Example\n\nCode: `fmt.Println()`"
}

# Convert an HTML file to Markdown
pandoc input.html -f html -t markdown -o output.md

# Pipe HTML from stdin
echo '<p>Hello <em>world</em></p>' | pandoc -f html -t markdown
# → Hello *world*

# Use GitHub-Flavored Markdown output
pandoc input.html -f html -t gfm -o output.md

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