تبدیل HTML به Markdown

تبدیل HTML به Markdown چیست؟

تبدیل HTML به Markdown، نشانه‌گذاری HTML را به Markdown تبدیل می‌کند؛ یک روش قالب‌بندی متن ساده و سبک که توسط John Gruber در سال ۲۰۰۴ ایجاد شد. 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 گامی رایج هنگام مهاجرت وب‌سایت‌ها، وارد کردن محتوای CMS یا آرشیو صفحات وب در قالبی قابل حمل است. برخلاف 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

سوالات متداول