Trình Chuyển Đổi Markdown Sang HTML

Cách hoạt động

1. Dán Markdown: nhập bất kỳ văn bản Markdown nào, tiêu đề, đoạn văn, danh sách, khối mã, bảng, trích dẫn và liên kết.
2. Chuyển đổi: công cụ phân tích Markdown và tạo HTML sạch và ngữ nghĩa với các phần tử lồng nhau hợp lý.
3. Xem trước hoặc sao chép: xem trước kết quả hoặc sao chép HTML thô để dán vào CMS, trang web hoặc mẫu email của bạn.

Lịch sử Ngắn của Markdown

Markdown được tạo bởi John Gruber, người viết đằng sau weblog Daring Fireball, với phản hồi thiết kế đáng kể từ Aaron Swartz. Bản phát hành công khai đầu tiên, phiên bản 1.0, được công bố trên trang web của Gruber vào ngày 9 tháng 3 năm 2004; phiên bản 1.0.1, bản phát hành tham chiếu kinh điển, theo sau vào 17 tháng 12 năm 2004 và vẫn là phiên bản được liên kết từ daringfireball.net/projects/markdown. Markdown là hai thứ cùng một lúc ngay từ đầu: một cú pháp định dạng văn bản thuần và tập lệnh Perl gốc đã chuyển đổi nó sang HTML. Mục tiêu được Gruber tuyên bố là văn bản nguồn phải có thể đọc được như nó vốn có, một tài liệu Markdown mở trong trình chỉnh sửa văn bản thuần phải trông giống như một email được định dạng cẩn thận, không phải súp thẻ. Ràng buộc khả năng đọc đó là ranh giới triết học phân tách Markdown khỏi các định dạng dựa trên XML và khỏi các markup nặng hơn như LaTeX, và là lý do mọi tiện ích mở rộng sau này phải tự bảo vệ mình về việc nó làm gián đoạn nguồn nghiêm trọng đến mức nào. Aaron Swartz trước đó đã viết một markup nhẹ liên quan gọi là atx (2002), góp phần vào kiểu heading # và ## giờ quen thuộc, đôi khi vẫn được gọi là "heading kiểu atx" trong các spec parser.

CommonMark, Khắc phục Underspecification

Mô tả cú pháp gốc của Gruber năm 2004 nổi tiếng không chính thức, một tài liệu văn xuôi với các ví dụ, không phải ngữ pháp. Nó để lại hàng chục trường hợp biên không được chỉ định, và Gruber không bao giờ phát hành parser tham chiếu nào khác ngoài tập lệnh Perl của ông, hành vi của nó độc đáo theo những cách mà các implementer khác phải sao chép hoặc ghi đè. Kết quả vào đầu những năm 2010 là GitHub, Reddit, Stack Overflow, Pandoc và parser Discount C đều render cùng một nguồn Markdown hơi khác nhau. Năm 2012, đồng sáng lập Stack Overflow Jeff Atwood và tác giả Pandoc John MacFarlane đã bắt đầu một nỗ lực viết một đặc tả thực sự, có thể kiểm tra được. Dự án ra mắt công khai vào tháng 9 năm 2014 với tên "Standard Markdown"; trong vòng vài ngày Gruber phản đối tên này trong email riêng, Atwood viết một bài đăng công khai giải thích sự thay đổi, và dự án được đổi thương hiệu thành "CommonMark". Bản phát hành đánh số đầu tiên đến vào ngày 25 tháng 10 năm 2014. Phiên bản đã xuất bản hiện tại là CommonMark 0.31.2, phát hành ngày 28 tháng 1 năm 2024. Đặc tả CommonMark khác thường ở chỗ chính nó là một tài liệu CommonMark, với 600+ trường hợp kiểm tra có thể thực thi inline; một parser tuyên bố tuân thủ bằng cách vượt qua các bài kiểm tra đó. GitHub Flavored Markdown (GFM), đặc tả chính thức ở phiên bản 0.29-gfm ngày 6 tháng 4 năm 2019, định nghĩa năm phần mở rộng trên CommonMark: bảng, mục danh sách công việc, strikethrough, autolinks cho URL trần, và HTML thô không được phép (một hạn chế bảo mật loại bỏ các thẻ nguy hiểm khỏi HTML do tác giả cung cấp).

Các Parser Chính

marked.js được tạo bởi Christopher Jeffrey vào năm 2011 và đã được tổ chức GitHub markedjs duy trì kể từ 2018, một thiết kế single-pass, lexer-then-parser ưu tiên tốc độ thô; ~36k sao và là dự án Markdown được gắn sao nhiều nhất trên GitHub. Đó là parser mà công cụ này sử dụng cho việc chuyển đổi. markdown-it được ra mắt vào năm 2014 bởi Vitaly Puzrin và Alex Kocharin, quảng bá tuân thủ CommonMark 100% với các toggle GFM tùy chọn cộng với một hệ sinh thái plugin tích cực (markdown-it-footnote, markdown-it-emoji, markdown-it-attrs, markdown-it-anchor và vài trăm cái khác). Đó là parser được sử dụng bởi preview Markdown tích hợp của VS Code, UI web của GitLab, và Eleventy. remark / unified.js không phải là một parser đơn lẻ mà là một framework biến đổi cây, tập thể unified định nghĩa một đặc tả cây cú pháp trừu tượng gọi là mdast (Markdown AST); remark phân tích Markdown thành mdast, các plugin thao tác cây, và remark-rehype chuyển đổi mdast thành hast (HTML AST) để phát ra. Chậm hơn marked nhưng có thể kết hợp được nhiều hơn; người dùng đáng chú ý bao gồm Prettier, Gatsby, MDN và linter ngôn ngữ bao trùm alex. Pandoc, phát hành bởi John MacFarlane vào ngày 10 tháng 8 năm 2006, là trình chuyển đổi tài liệu phổ quát, được viết bằng Haskell, phân tích khoảng 30 định dạng đầu vào, render thành khoảng 40 định dạng đầu ra; phổ biến trong xuất bản học thuật và kỹ thuật.

Pipeline MD-sang-HTML, Một cách Cơ học

Một parser Markdown thường hoạt động trong hai pass. Phân tích cấp khối chia đầu vào thành các cấu trúc khối, đoạn văn, heading, danh sách, code fences, blockquote, đường ngang, bảng. Ranh giới khối được xác định bởi các dòng trống và thụt lề; làm đúng chúng là phần lớn những gì làm cho một parser CommonMark đúng. Phân tích inline sau đó đi qua nội dung của mỗi khối và khớp với cú pháp inline: nhấn mạnh (*italic*, **bold**), liên kết ([text](url)), code span inline (`code`), hình ảnh (![alt](url)), strikethrough (~~text~~ trong GFM), và autolinks rõ ràng (<https://example.com>). Phân tích nhấn mạnh inline là phần khó nhất của bất kỳ đặc tả Markdown nào, CommonMark dành nhiều trang của đặc tả và hàng tá trường hợp kiểm tra cho việc chỉ định khi nào *foo*bar* sẽ tạo ra <em>foo</em>bar* so với *foo<em>bar</em>. Parser sau đó render mỗi token thành phần tử HTML tương ứng và nối các kết quả. Pretty printing, thụt lề, và syntax highlighting cho khối mã được phủ trên bằng các tùy chọn render.

Tại sao Phải Chuyển đổi MD sang HTML Trước hết?

• Nhập CMS. Nhiều CMS headless (Contentful, Sanity, Wagtail, Ghost) chấp nhận HTML nhưng không Markdown. Lập bản nháp trong Markdown và chuyển đổi một lần khi xuất bản giữ trải nghiệm chỉnh sửa thoải mái.
• Soạn thảo email. Các email client render HTML; hầu hết không render Markdown. Các nền tảng newsletter (Mailchimp, ConvertKit, Substack) thường chấp nhận HTML được dán vào trình chỉnh sửa của họ. Chuyển đổi bản nháp, dán, gửi.
• Bản nháp bài đăng blog. Một số cài đặt WordPress legacy không có plugin Markdown yêu cầu HTML trong nội dung bài đăng; một số trang shop Shopify và Webflow chấp nhận HTML trong các trường rich-text của họ.
• Snippet cho trình tạo trang tĩnh. Khi bạn cần một khối HTML inline cho một shortcode Hugo, một template Eleventy hoặc một tệp MDX Next.js, chuyển đổi Markdown thành một mảnh HTML đơn nhanh hơn việc chiến đấu với pipeline chuyển đổi của chính SSG.
• Chia sẻ ghi chú đã được render. Dán Markdown "đã được render" vào Slack, Notion, Linear, ClickUp hoặc các đích đến rich-text khác đôi khi muốn HTML trên clipboard thay vì Markdown thô.
• Lưu trữ tài liệu. Lưu trữ HTML đã được render cùng với nguồn Markdown có nghĩa là kho lưu trữ của bạn có thể đọc được bởi con người trong trình duyệt mà không cần parser, hữu ích cho bảo tồn lâu dài.

Các Tùy chọn Đầu ra Đáng Biết

Các sử dụng downstream khác nhau muốn những thứ khác nhau từ HTML đã chuyển đổi. Tài liệu đầy đủ vs đoạn. Một tài liệu HTML đầy đủ bao gồm <!DOCTYPE html>, <html>, <head> với metadata, và một wrapper <body>, phù hợp khi bạn sẽ lưu tệp dưới dạng .html và mở trong trình duyệt. Một đoạn chỉ là nội dung body, không có wrapper, phù hợp khi bạn sẽ dán vào một trường CMS đã cung cấp cấu trúc tài liệu. Công cụ này phát ra các đoạn theo mặc định; bao bọc bằng boilerplate của riêng bạn nếu bạn cần một tài liệu hoàn chỉnh. Khử trùng. Theo mặc định các parser Markdown đi qua HTML thô không thay đổi, vì vậy nếu nguồn của bạn chứa <script>alert(1)</script>, thẻ script đó sẽ xuất hiện trong đầu ra. Đối với các tài liệu đi vào hệ thống đa người dùng, chạy đầu ra qua DOMPurify (Cure53, bắt đầu tháng 2 năm 2014) trước khi tiêm vào DOM. Đối với sử dụng cá nhân một lần, đầu ra thô là tốt. ID Header. Tạo thuộc tính id trên heading (được slugify từ văn bản heading) cho phép bạn xây dựng mục lục với liên kết anchor. Thuật toán slug chính xác khác nhau giữa các nền tảng, GitHub sử dụng một quy tắc, MkDocs một quy tắc khác, marked.js một quy tắc thứ ba, vì vậy liên kết anchor có thể bị hỏng khi nội dung di chuyển giữa các hệ thống. Hard line break. CommonMark yêu cầu hoặc hai dấu cách trailing ở cuối dòng hoặc một backslash để buộc <br>; một số nền tảng (Discord, GitHub issues) coi các newline đơn là ngắt. Lựa chọn phụ thuộc vào phong cách dự kiến của nguồn của bạn.

Các Cạm bẫy Phổ biến

• Chuyển đổi smart-quote. Một số parser (hoặc các lớp hậu xử lý như SmartyPants của chính Gruber) thay thế dấu nháy thẳng bằng dấu nháy typographic cong theo mặc định. Nếu bạn cần dấu nháy thẳng được bảo toàn (vì đầu ra của bạn đang được phân tích như mã), kiểm tra rằng phép biến đổi này đã tắt.
• Độ nhạy whitespace của marker danh sách. Trộn - và * và + trong cùng một danh sách, thụt lề các đoạn văn tiếp tục danh sách ít hơn yêu cầu của marker, hoặc đặt một dòng trống giữa các mục danh sách có thể lật một danh sách chặt thành một danh sách lỏng (mỗi mục được bọc trong thẻ <p>). Sự khác biệt trực quan trong đầu ra là kịch tính.
• Sự quá sốt sắng của autolink. Autolinking kiểu GFM biến bất kỳ URL trần nào thành một liên kết, đó thường là điều bạn muốn, nhưng có thể làm hỏng các URL chứa dấu ngoặc đơn (đặc biệt là URL Wikipedia) hoặc dấu câu trailing.
• Bảng cần escape. Các ký tự pipe bên trong ô bảng phải được escape thành \|, nếu không chúng được đọc như dấu phân cách cột. Bắt bất cứ ai cố gắng đặt một ví dụ mã một dòng bên trong một ô.
• Markdown và HTML hỗn hợp. Markdown được thiết kế để đi qua HTML tùy ý, vì vậy thả một <div class="callout"> vào tệp Markdown hoạt động. Nhưng khoảnh khắc bạn đặt cú pháp Markdown bên trong một khối HTML, các parser phân kỳ: CommonMark coi hầu hết các khối HTML là opaque; Markdown Extra đã giới thiệu markdown="1" để chọn tham gia parsing lồng nhau.
• ID heading giữa các nền tảng. Các thuật toán slugify khác nhau tạo ra các đoạn anchor khác nhau cho cùng một heading; các liên kết trong tài liệu có thể bị hỏng khi nội dung di chuyển giữa các hệ thống.

Công cụ Này vs Markdown Previewer

Absolutool cung cấp hai công cụ liên quan chồng chéo trên cùng một parser. Markdown Previewer dành cho chỉnh sửa trực tiếp, viết Markdown bên trái, xem đầu ra trực quan được render bên phải, không có khái niệm về "đầu ra HTML". Bộ chuyển đổi Markdown-sang-HTML này dành cho chuyển đổi một lần, dán Markdown, sao chép HTML thô, dán vào CMS hoặc email client của bạn. Sử dụng previewer khi bạn đang lập bản nháp và cần phản hồi trực quan; sử dụng bộ chuyển đổi này khi bạn có Markdown đã hoàn thành và cần HTML mà bạn có thể vận chuyển đi nơi khác. Cả hai công cụ đều sử dụng marked.js bên dưới mui xe và chấp nhận cùng phương ngữ CommonMark + GFM, vì vậy hành vi chuyển đổi giống hệt nhau giữa chúng.

Quyền riêng tư: Tại sao chỉ-Trình duyệt Quan trọng ở đây

Bản nháp của các bài viết chưa xuất bản, bài đăng blog đang tiến hành, tài liệu nội bộ, deliverable khách hàng dưới NDA, các chương bản thảo, các bài báo học thuật, chính xác là loại văn bản bạn không muốn tải lên dịch vụ bên thứ ba. Các bộ chuyển đổi Markdown phía máy chủ yêu cầu gửi toàn bộ tài liệu đến một endpoint từ xa, có nghĩa là nó nằm trong nhật ký máy chủ, có thể trong bộ nhớ cache CDN, có thể trong pipeline phân tích, có thể trong sao lưu. Đối với văn bản đã xuất bản, vấn đề là vô nghĩa. Đối với công việc bản nháp, kiến trúc quan trọng. Công cụ này chạy toàn bộ pipeline trong trình duyệt của bạn qua JavaScript và marked.js. Markdown không bao giờ băng qua mạng, xác minh trong tab Network của DevTools khi bạn gõ, hoặc đưa trang offline (chế độ máy bay) sau khi tải và xác nhận bộ chuyển đổi vẫn hoạt động. An toàn cho bản nháp bí mật, deliverable khách hàng, các chương bản thảo dưới NDA, ghi chú nội bộ hoặc bất cứ điều gì khác mà bạn không muốn được sao chép vào ổ cứng của người lạ.

Câu hỏi thường gặp

Bộ chuyển đổi này hỗ trợ phương ngữ Markdown nào?

CommonMark với các phần mở rộng GFM phổ biến nhất được bật, bảng (phân cách bằng pipe với căn chỉnh : tùy chọn), khối mã được rào với gợi ý ngôn ngữ, strikethrough qua ~~text~~, autolinks cho URL trần, và mục danh sách công việc qua [ ] và [x]. Heading, đậm, nghiêng, liên kết, hình ảnh, danh sách, blockquote, đường ngang và mã inline đều hoạt động như bạn mong đợi trên GitHub. Trình render là marked.js, cùng parser mà Markdown Previewer sử dụng.

Điều này có hỗ trợ GitHub Flavored Markdown (GFM) không?

Có, bảng với pipe, khối mã rào với gợi ý ngôn ngữ, danh sách task, autolinks và strikethrough đều hoạt động. Nếu một phần mở rộng GFM không được render, kiểm tra lại đầu vào tuân theo các quy tắc cú pháp CommonMark/GFM: dòng trống xung quanh các phần tử khối, số lượng backtick khớp trên các khối mã rào, chính xác hai khoảng trắng trailing (hoặc một backslash) cho hard line break. Nguyên nhân phổ biến nhất của "GFM không hoạt động" là một trình chỉnh sửa loại bỏ khoảng trắng trailing khi lưu, điều này giết cú pháp hard-break.

Đầu ra sẽ trông giống như trên GitHub không?

HTML cấu trúc, đoạn văn, danh sách, bảng, heading, sẽ khớp cho bất kỳ đầu vào nào là CommonMark + GFM hợp lệ. Hai lớp sẽ khác nhau. GitHub áp dụng chủ đề CSS của riêng mình và syntax-highlighting, vì vậy màu sắc, phông chữ và khoảng cách sẽ trông khác nhau. GitHub cũng phủ hậu xử lý lên đặc tả, mã ngắn emoji (:smile:), đề cập @user, tự động liên kết #issue, đường dẫn hình ảnh tương đối với repository, mà không có bộ chuyển đổi tuân thủ spec nào tái tạo. HTML mà công cụ này phát ra có thể di động về mặt cấu trúc; ngoại hình trực quan phụ thuộc vào CSS ở đích đến.

Tôi có nên khử trùng đầu ra trước khi xuất bản không?

Nếu nguồn có thể bao gồm nội dung do người dùng cung cấp, có. Các parser Markdown đi qua HTML thô không thay đổi, vì vậy một nguồn chứa <img src=x onerror="alert(1)"> sẽ tạo ra thẻ đó trong đầu ra. Đối với hệ thống đa người dùng, chạy đầu ra qua DOMPurify (Cure53, tháng 2 năm 2014, sanitizer JavaScript de-facto) trước khi tiêm vào DOM. Đối với sử dụng cá nhân một lần nơi nguồn là bài viết của chính bạn, đây không phải là vấn đề, điều tồi tệ nhất bạn có thể làm với trang của riêng mình là dán HTML của riêng bạn.

Tôi có thể nhận được tài liệu HTML đầy đủ với head và body không?

Hiện tại công cụ này phát ra chỉ đoạn body, Markdown đã chuyển đổi được bọc trong các thẻ HTML ngữ nghĩa nhưng không phải trong một tài liệu <html>/<head>/<body> đầy đủ. Để lưu dưới dạng tệp .html độc lập, tự bao bọc đầu ra: <!DOCTYPE html><html><head><meta charset="utf-8"><title>...</title></head><body>[fragment]</body></html>. Hoặc sử dụng Pandoc với cờ --standalone cho đầu ra hoàn toàn độc lập với CSS được điều khiển bởi template.

Markdown của tôi có được gửi đi đâu không?

Không. Chuyển đổi chạy hoàn toàn trong trình duyệt của bạn qua marked.js. Markdown bạn dán không bao giờ băng qua mạng, xác minh trong tab Network của DevTools khi bạn gõ, hoặc đưa trang offline (chế độ máy bay) sau khi tải và xác nhận bộ chuyển đổi vẫn hoạt động. An toàn cho bản nháp bí mật, deliverable khách hàng dưới NDA, các chương bản thảo hoặc bất kỳ văn bản nào bạn không muốn được sao chép vào ổ cứng của người lạ.

Công cụ liên quan