Chuyển đổi HTML to Markdown sẽ giúp lập trình viên xử lý dữ liệu đầu ra cho các hệ thống viết tài liệu, blog tĩnh hoặc tự động hóa trong CI/CD. Bài viết này sẽ tập trung vào cách sử dụng các thư viện lập trình bằng JavaScript, Node.js và PHP để thực hiện việc chuyển đổi một cách linh hoạt, dễ tùy biến và dễ tích hợp vào các project thực tế.
Đọc bài viết sau để được giải đáp chi tiết hơn về:
- Markdown là gì? Tại sao cần chuyển đổi dữ liệu từ HTML to Markdown?
- Hướng dẫn chi tiết 3 cách chuyển đổi HTML sang Markdown bằng thư viện lập trình: JavaScript, Python và PHP.
- Một số câu hỏi thường gặp khi chuyển đổi dữ liệu từ HTML sang Markdown.
Markdown là gì?
Markdown là một ngôn ngữ đánh dấu nhẹ (lightweight markup language), được John Gruber tạo ra vào năm 2004. Markdown hiện là một trong những ngôn ngữ đánh dấu phổ biến nhất thế giới.
Phần mở rộng của tệp Markdown là .md hoặc .markdown. Để chuyển đổi tệp Markdown, bạn cần một ứng dụng có khả năng xử lý các tệp markdown như Visual Studio Code, Typora, Dillinger, Obsidian hoặc Mark Text, Dillinger,… Các ứng dụng này sử dụng bộ xử lý hoặc trình phân tích cú pháp Markdown để chuyển đổi tệp markdown thành mã HTML có thể in được.
Cú pháp của Markdown là gì?
Dưới đây là những cú pháp của Markdown có thể được dùng làm tài liệu tham khảo khi bạn viết mã Markdown.
Heading
# Header1 ## Header2 ### Header3 #### Header4 ....
Kết quả hiển thị của đoạn mã trên:
Định dạng
*This is Italic* _This is also Italic_ **This is bold** __This is also bold__ __This is a **combination**__
Kết quả hiển thị của đoạn mã trên:
Danh sách
1. One 2. Two 3. Three - Elem 1 - Elem 2 * Member * Another Member - Elem Main - Another one - Sub list - It's Member
Kết quả hiển thị của đoạn mã trên:
Hình ảnh và liên kết
IMAGE :  LINK : [ITviec](https://itviec.com/)
Mã và câu trích (câu quote)
``` Html <h1>đây là code block</h1> ``` Here Code is `Inline` . > These are > Some Quotes
Kết quả hiển thị của đoạn mã trên:
Checklist
- [x] Việc đã xong - [ ] Việc chưa xong
Kết quả hiển thị của đoạn mã trên:
Bảng
| Tên | Tuổi | Nghề nghiệp | |---------|------|----------------| | An | 25 | Lập trình viên | | Bình | 30 | Thiết kế |
Kết quả hiển thị của đoạn mã trên:
Ưu điểm của Markdown
Markdown sẽ giúp tạo các thành phần HTML cơ bản mà bạn thấy trên trang web như văn bản, danh sách, liên kết, hình ảnh và nhiều thành phần khác. Ưu điểm của Markdown là:
- Có thể chuyển đổi sang các định dạng như PDF, HTML, tài liệu,…
- Bạn có thể định dạng nội dung email bằng Markdown với MarkdownHere.
- Được sử dụng rộng rãi để viết các trang được định dạng trên nhiều nền tảng khác nhau như StackOverflow, Github và nhiều nền tảng khác.
- File Markdown có thể được chuyển đổi thành trang web bằng các công cụ như Github Pages, blot.im và smallvictori.es.
- Khi nội dung gốc ở dạng Markdown, bạn có thể dễ dàng chuyển lại thành HTML khi cần sử dụng trên website mà không lo mất dữ liệu định dạng.
Tại sao cần chuyển đổi HTML sang Markdown?
Một số lý do phổ biến khi bạn cần chuyển đổi HTML sang Markdown như:
- Dễ chỉnh sửa và đọc hiểu hơn: Markdown có cú pháp đơn giản, rõ ràng, giúp lập trình viên hay người dùng không chuyên dễ dàng đọc, chỉnh sửa nội dung.
- Tối ưu hóa tài liệu cho hệ thống quản lý nội dung (CMS): GitHub, GitLab, Notion, hoặc các nền tảng viết blog (Hugo, Jekyll) đều hỗ trợ tốt Markdown hơn HTML.
- Dễ tích hợp vào quy trình DevOps: Trong các dự án CI/CD, việc lưu trữ tài liệu dưới định dạng Markdown giúp tự động hóa tốt hơn. Bởi vì Markdown có cấu trúc đơn giản, dễ đọc và dễ dàng kết hợp với các công cụ kiểm thử.
- Nhẹ hơn, tải nhanh hơn: Markdown là văn bản thuần, nhẹ và dễ nén hơn HTML. Khi cần hiển thị, Markdown sẽ được chuyển đổi sang HTML, nhưng bản thân tệp Markdown rất nhẹ và phù hợp để dùng trong tài liệu nội bộ hoặc ghi chú dự án.
Chi tiết 3 cách chuyển đổi HTML to Markdown bằng thư viện lập trình
Nếu là lập trình viên, bạn có thể lựa chọn chuyển đổi HTML sang Markdown bằng thư viện lập trình như JavaScript, Python hay PHP. Những cách này sẽ giúp bạn quá trình chuyển đổi chính xác và dễ tùy biến hơn. Dưới đây là chi tiết về 3 cách chuyển đổi file phổ biến:
| Thư viện | Cách sử dụng | Ưu/ Nhược điểm |
| turndown
(JavaScript) |
|
Ưu điểm:
Nhược điểm:
|
| markdownify
(Python) |
|
Ưu điểm:
Nhược điểm:
|
| league/html-to-markdown
(PHP) |
|
Ưu điểm:
Nhược điểm:
|
Chuyển đổi HTML sang Markdown với thư viên turndown của JavaScript
JavaScript là lựa chọn phổ biến nếu bạn muốn chuyển đổi HTML sang Markdown ngay trên trình duyệt hoặc trong môi trường client-side. Một trong những thư viện nổi bật và dễ sử dụng nhất là turndown.
Bạn có thể cài đặt thư viện turndown bằng npm với đoạn code npm install turndown hoặc nhúng đường dẫn CDN
<script src="https://unpkg.com/turndown/dist/turndown.js"></script>.
Ví dụ về chuyển đổi markdown bằng turndown:
var TurndownService = require('turndown')
var turndownService = new TurndownService()
var markdown = turndownService.turndown('<h1>Hello world!</h1>')
Ngoài ra, Turndown cũng chấp nhận các Node trong DOM làm đầu vào (hoặc element nodes, document nodes hoặc document fragment nodes):
var markdown = turndownService.turndown(document.getElementById('content'))
Ngoài ra, tùy chọn có thể được thông qua vào hàm khi khởi tạo. Chẳng hạn như:
var turndownService = new TurndownService({ option: 'value' })
Bạn có thể thực hiện chuyển đổi với một số phương pháp thường được sử dụng trong thư viện turndown như sau:
addRule(key, rule)
Tham số key tên duy nhất cho quy tắc để dễ tham chiếu. Ví dụ như:
turndownService.addRule('strikethrough', {
filter: ['del', 's', 'strike'],
replacement: function (content) {
return '~' + content + '~'
}
})
Kết quả, addRule trả về chính instance của TurndownService, cho phép gọi tiếp các phương thức khác (method chaining).
keep(filter)
Phương pháp giúp xác định các phần tử nào sẽ được giữ nguyên và hiển thị dưới dạng HTML. Theo mặc định, Turndown không giữ lại bất kỳ phần tử nào, do đó tham số filter sẽ hoạt động giống như một bộ lọc quy tắc. Ví dụ:
turndownService.keep(['del', 'ins']) turndownService.turndown('<p>Hello <del>world</del><ins>World</ins></p>') // 'Hello <del>world</del><ins>World</ins>'
Điều này sẽ hiển thị các phần tử <del> và <ins> dưới dạng HTML khi được chuyển đổi.
Bạn có thể gọi keep nhiều lần, và mỗi bộ lọc keep mới thêm vào sẽ được ưu tiên hơn các bộ lọc cũ. Tuy nhiên, các bộ lọc keep này vẫn có thể bị ghi đè bởi các quy tắc chuẩn của CommonMark hoặc bất kỳ quy tắc bổ sung nào khác. Nếu bạn muốn giữ lại các phần tử mà thông thường sẽ bị xử lý bởi những quy tắc đó, hãy thêm một quy tắc riêng với hành vi bạn mong muốn.
remove(filter)
remove(filter) sẽ xác định phần tử nào sẽ bị xóa hoàn toàn, nghĩa là chuyển đổi thành chuỗi rỗng. Với ví dụ bên dưới, thao tác sẽ xóa tất cả nội dung có trong phần tử <del> :
turndownService.remove('del') turndownService.turndown('<p>Hello <del>world</del><ins>World</ins></p>') // 'Hello World'
use(plugin|array)
Sử dụng một plugin hoặc một mảng các plugin.
// Import plugins from turndown-plugin-gfm var turndownPluginGfm = require('turndown-plugin-gfm') var gfm = turndownPluginGfm.gfm var tables = turndownPluginGfm.tables var strikethrough = turndownPluginGfm.strikethrough // Use the gfm plugin turndownService.use(gfm) // Use the table and strikethrough plugins only turndownService.use([tables, strikethrough])
Đoạn mã trên đã sử dụng plugin turndown-plugin-gfm để chuyển đổi HTML sang Markdown, đặc biệt là theo chuẩn GitHub Flavored Markdown (GFM).
- gfm: là một plugin tổng hợp, bao gồm nhiều tính năng của GFM như bảng (tables), gạch ngang (strikethrough), danh sách nhiệm vụ (task list),…
- tables: chỉ xử lý chuyển đổi bảng HTML sang bảng Markdown.
- strikethrough: xử lý các thẻ <del> hoặc đoạn văn bản bị gạch ngang.
Chuyển đổi HTML sang Markdown với thư viện markdownify của Python
Python là một ngôn ngữ phổ biến trong xử lý dữ liệu, web scraping và tự động hóa. Nếu bạn đang làm việc với nội dung HTML và muốn chuyển đổi sang Markdown thì có thể cân nhắc đến thư viện markdownify của Python.
Thư viện sẽ cung cấp một số tùy chọn (options) như sau:
- strip: Cho phép loại bỏ các thẻ HTML nhất định, nhưng giữ lại nội dung văn bản bên trong. Không thể sử dụng cùng với tùy chọn convert
- convert: Danh sách các thẻ HTML cần chuyển đổi. Không thể sử dụng cùng với tùy chọn strip
- autolinks: Boolean, xác định xem có sử dụng kiểu “liên kết tự động” khi nội dung của thẻ <a> khớp với href của nó không. Mặc định là True
- default_title: Boolean, cho phép đặt tiêu đề của liên kết bằng href nếu không có tiêu đề. Mặc định là False
- heading_style: Xác định cách chuyển đổi các tiêu đề. Các giá trị hợp lệ: ATX, ATX_CLOSED, SETEXT, UNDERLINED (alias của SETEXT). Mặc định là UNDERLINED
- bullets: Một chuỗi hoặc danh sách các kiểu dấu đầu dòng. Nếu chỉ có một kiểu, nó sẽ được sử dụng cho tất cả các cấp độ. Mặc định là *+-.
- strong_em_symbol: Xác định ký tự sử dụng để mã hóa văn bản đậm hoặc nghiêng. Có thể là dấu sao * (mặc định) hoặc dấu gạch dưới _
- sub_symbol, sup_symbol: Xác định ký tự bao quanh văn bản <sub> và <sup>. Mặc định là chuỗi rỗng (hành vi không chuẩn). Có thể sử dụng các ký tự như ~ và ^ để tạo ra các dạng như ~sub~ và ^sup^
- newline_style: Xác định kiểu đánh dấu xuống dòng <br> trong Markdown. Mặc định là SPACES (hai dấu cách và một dòng mới). Nếu chọn BACKSLASH, sẽ chuyển đổi xuống dòng thành \\n
- code_language: Xác định ngôn ngữ của tất cả các phần <pre>. Hữu ích nếu tất cả mã trên trang sử dụng cùng một ngôn ngữ. Mặc định là chuỗi rỗng (”)
Ví dụ về cách chuyển đổi HTML sang Markdown bằng thư viện Python:
Chuyển đổi thẻ <b> thành ** (Markdown cho chữ đậm) và thẻ <a> thành cú pháp liên kết Markdown [GitHub](http://github.com).
from markdownify import markdownify as md md('<b>Yay</b> <a href="http://github.com">GitHub</a>') # Kết quả: '**Yay** [GitHub](http://github.com)'
Loại bỏ một số thẻ HTML bằng cách loại bỏ thẻ <a> khỏi HTML, chỉ giữ lại nội dung của thẻ <b> chuyển thành **Yay** và giữ nguyên “GitHub”.
from markdownify import markdownify as md md('<b>Yay</b> <a href="http://github.com">GitHub</a>', strip=['a']) # Kết quả: '**Yay** GitHub'
Chỉ chuyển đổi một số thẻ HTML như <b> thành Markdown cho chữ đậm (**Yay**) và giữ nguyên thẻ <a> như là văn bản bình thường “GitHub”.
from markdownify import markdownify as md
md('<b>Yay</b> <a href="http://github.com">GitHub</a>', convert=['b']) # Kết quả: '**Yay** GitHub'
Chuyển đổi HTML sang Markdown với thư viện PHP
Nếu bạn đang làm việc với hệ thống CMS hoặc backend viết bằng PHP (như WordPress hoặc Laravel), bạn có thể sử dụng thư viện league/html-to-markdown.
Để sử dụng thư viện, bạn sẽ yêu cầu thư viện bằng cách sử dụng dòng lệnh và thêm require ‘vendor/autoload.php’; vào đầu tập lệnh của bạn.
composer require league/html-to-markdown
Tiếp theo, tạo một phiên bản HtmlConverter mới, nhập mã HTML hợp lệ của bạn vào hàm convert():
use League\HTMLToMarkdown\HtmlConverter; $converter = new HtmlConverter(); $html = "<h3>Nhanh lên, đến Batpoles!</h3>"; $markdown = $converter->convert($html);
Biến $markdown sẽ chứa phiên bản Markdown của HTML của bạn dưới dạng chuỗi:
echo $markdown; // ==> ### Nhanh lên, đến Batpoles!
Tùy chọn chuyển đổi (Conversion options)
Thư viện league/html-to-markdown sẽ giữ lại các thẻ HTML không có tương đương trong Markdown, như <span>, <div>, <iframe>, <script>,… Do đó, bạn có thể cân nhắc thiết lập các tùy chọn strip_tags, remove_nodes hoặc một thư viện (như HTML Purifier) để cung cấp thêm bộ lọc HTML.
Để loại bỏ các thẻ HTML không có tương đương trong Markdown nhưng vẫn giữ lại nội dung bên trong, bạn hãy đặt strip_tags thành true, như sau:
$converter = new HtmlConverter(array('strip_tags' => true)); $html = '<span>Turnips!</span>'; $markdown = $converter->convert($html); // $markdown now contains "Turnips!"
Hoặc để loại bỏ cả thẻ và nội dung bên trong, bạn có thể nhập vào danh sách các thẻ cần loại bỏ, cách nhau bằng dấu cách trong remove_nodes, như sau:
$converter = new HtmlConverter(array('remove_nodes' => 'span div')); $html = '<span>Turnips!</span><div>Monkeys!</div>'; $markdown = $converter->convert($html); // $markdown bây giờ chứa ""
Mặc định, tất cả các comment HTML sẽ bị loại bỏ khỏi nội dung. Để giữ lại chúng, bạn có thể sử dụng tùy chọn preserve_comments, như sau:
$converter = new HtmlConverter(array('preserve_comments' => true)); $html = '<span>Turnips!</span><!-- Monkeys! -->'; $markdown = $converter->convert($html); // $markdown now contains "Turnips!<!-- Monkeys! -->"
Để chỉ giữ lại những bình luận cụ thể, bạn có thể thiết lập preserve_comments với một mảng các chuỗi, như sau:
$converter = new HtmlConverter(array('preserve_comments' => array('Eggs!'))); $html = '<span>Turnips!</span><!-- Monkeys! --><!-- Eggs! -->'; $markdown = $converter->convert($html); // $markdown bây giờ chứa "Turnips!<!-- Eggs! -->"
Mặc định, các liên kết thay thế (placeholder links) sẽ được giữ lại. Để loại bỏ các liên kết thay thế này, bạn có thể sử dụng tùy chọn strip_placeholder_links, như sau:
$converter = new HtmlConverter(array('strip_placeholder_links' => true));
$html = '<a>Github</a>';
$markdown = $converter->convert($html); // $markdown bây giờ chứa "Github"
Định dạng (style options)
Các thẻ <b> sẽ được chuyển đổi bằng cú pháp dấu sao (*), và các thẻ <i> sẽ được chuyển đổi bằng cú pháp dấu gạch dưới (_). Bạn có thể thay đổi các cú pháp này bằng cách sử dụng các tùy chọn bold_style và italic_style.
$converter = new HtmlConverter();
$converter->getConfig()->setOption('italic_style', '*');
$converter->getConfig()->setOption('bold_style', '__');
$html = '<em>Italic</em> and a <strong>bold</strong>';
$markdown = $converter->convert($html); // $markdown now contains "*Italic* and a __bold__"
Ngắt dòng (Line break options)
Các thẻ <br> sẽ được chuyển đổi thành hai dấu cách, sau đó là ký tự xuống dòng theo kiểu Markdown truyền thống. Nếu bạn muốn bỏ qua hai dấu cách và tuân theo quy chuẩn của GitHub Flavored Markdown (GFM), hãy đặt hard_break thành true.
$converter = new HtmlConverter(); $html = '<p>test<br>line break</p>'; $converter->getConfig()->setOption('hard_break', true); $markdown = $converter->convert($html); // $markdown now contains "test\nline break" $converter->getConfig()->setOption('hard_break', false); // default $markdown = $converter->convert($html); // $markdown now contains "test \nline break"
Tự động liên kết (Autolinking options)
Mặc định, các thẻ <a> sẽ được chuyển đổi sang cú pháp liên kết đơn giản nhất. Cụ thể, nếu không có nội dung hiển thị (text) hoặc tiêu đề (title), cú pháp <url> sẽ được sử dụng thay vì cú pháp đầy đủ [url](url).
Nếu bạn muốn luôn sử dụng cú pháp đầy đủ cho liên kết, hãy đặt use_autolinks thành false.
$converter = new HtmlConverter(); $html = '<p><a href="https://thephpleague.com">https://thephpleague.com</a></p>'; $converter->getConfig()->setOption('use_autolinks', true); $markdown = $converter->convert($html); // $markdown now contains "<https://thephpleague.com>" $converter->getConfig()->setOption('use_autolinks', false); // default $markdown = $converter->convert($html); // $markdown now contains "[https://thephpleague.com](https://thephpleague.com)"
Câu hỏi thường gặp về chuyển đổi HTML thành Markdown
Markdown có giống HTML không?
Câu trả lời là không. HTML là ngôn ngữ đánh dấu siêu văn bản có cấu trúc phức tạp hơn, được sử dụng để tạo và định dạng các trang web. Trong khi đó, Markdown là ngôn ngữ đánh dấu nhẹ giúp bạn viết nội dung một cách đơn giản với cú pháp dễ nhớ, chủ yếu phục vụ viết tài liệu hoặc bài viết blog.
Có thể sử dụng HTML trong Markdown không?
Câu trả lời là có. Markdown hỗ trợ chèn mã HTML trực tiếp. Markdown cho phép người dùng sử dụng HTML để định dạng các cấu trúc phức tạp, hoặc khi bạn muốn thêm các phần tử như bảng tùy chỉnh, video nhúng hoặc các thuộc tính mà cú pháp Markdown không hỗ trợ. Tuy nhiên, không phải tất cả các trình chuyển đổi Markdown đều hỗ trợ HTML.
Ai cần sử dụng trình chuyển đổi HTML sang Markdown?
Trình chuyển đổi HTML to Markdown hữu ích cho nhiều đối tượng, bao gồm:
- Lập trình viên: Xử lý dữ liệu từ web và chuyển đổi nội dung HTML sang Markdown để sử dụng trong API hoặc hệ thống tài liệu.
- Blogger & Nhà viết nội dung: Xuất nội dung từ trình soạn thảo web sang Markdown để sử dụng trên các nền tảng hỗ trợ Markdown như GitHub, Jekyll, Hugo, hoặc Notion.
- DevOps & người làm CI/CD: Tạo tài liệu tự động từ dữ liệu web hoặc email, phục vụ cho hệ thống báo cáo nội bộ.
Những lỗi phổ biến khi chuyển HTML sang Markdown là gì?
Khi chuyển đổi HTML sang Markdown có thể gặp một số lỗi phổ biến như:
- Bỏ sót thẻ HTML: Một số thư viện lập trình chỉ hỗ trợ một tập hợp các thẻ HTML cơ bản (<p>, <h1>, <a>, <strong>, <em>, <ul>, <ol>). Để khắc phục, bạn kiểm tra thư viện có hỗ trợ chuyển đổi một số thẻ phức tạp như <table>, <figure>, hoặc <video> hay không, hoặc viết bộ chuyển đổi tùy chỉnh.
- Xử lý sai danh sách lồng nhau: Khi chuyển đổi danh sách <ul> hoặc <ol>, một số thư viện có thể làm sai định dạng Markdown, đặc biệt khi danh sách có nhiều cấp. Để khắc phục lỗi danh sách lồng nhau, bạn cần đảm bảo thư viện hỗ trợ indent chuẩn (thường là 2 hoặc 4 khoảng trắng cho cấp độ lồng).
- Bỏ qua thuộc tính hoặc class của HTML: Markdown không hỗ trợ trực tiếp CSS classes hoặc inline styles. Nếu bạn chuyển một đoạn HTML có class=”bold”, thì Markdown sẽ không thể giữ nguyên định dạng này.
- Không hỗ trợ các ký tự đặc biệt: Markdown sử dụng một số ký tự đặc biệt như *, _, #, > để định dạng văn bản. Nếu HTML có chứa các ký tự này, nhưng thư viện không xử lý tốt, có thể gây ra lỗi cú pháp Markdown.
- Lỗi về encoding ký tự (UTF-8): Khi HTML có ký tự đặc biệt hoặc ngôn ngữ không phải tiếng Anh (như tiếng Việt, Nhật, Trung), nếu encoding không chuẩn UTF-8, Markdown xuất ra có thể bị lỗi font hoặc ký tự bị mã hóa sai.
Khi chuyển đổi, bạn cần kiểm tra lại kết quả xuất file của Markdown không bị lỗi danh sách, bảng, hoặc mất dữ liệu quan trọng. Nếu Markdown không hỗ trợ tính năng nào đó, bạn có thể giữ lại HTML hoặc chuyển đổi theo cách thủ công.
Tổng kết
Chuyển đổi HTML to Markdown bằng thư viện lập trình là một lựa chọn phù hợp dành cho các lập trình viên cần tự động hóa quy trình hoặc xử lý nội dung động. Các thư viện như JavaScript, Python hay PHP đều cung cấp giải pháp nhanh chóng, linh hoạt và dễ tích hợp. Tùy thuộc vào ngôn ngữ và tính chất dự án, bạn có thể chọn thư viện phù hợp để xử lý nội dung HTML mà không cần thao tác thủ công.
Hy vọng những gợi ý từ ITviec sẽ giúp bạn tiết kiệm thời gian và tăng hiệu quả công việc hơn nhé!
Xem thêm: Giải đáp “tất tần tật” những điều cần biết về HTML