Markdown đang cản trở bạn
(newsletter.bphogan.com)- Markdown, vốn được dùng rộng rãi để viết tài liệu phát triển, rất phổ biến nhờ tính đơn giản và dễ tiếp cận, nhưng có giới hạn với tài liệu kỹ thuật quy mô lớn do thiếu khả năng biểu đạt cấu trúc
- Markdown hoạt động như một hệ thống kiểu ngầm định, khiến việc đảm bảo tính nhất quán hay kiểm tra schema là bất khả thi; đồng thời cũng tồn tại vấn đề tương thích giữa các biến thể Markdown (flavor) khác nhau
- Các cú pháp mở rộng như MDX giúp tăng khả năng biểu đạt, nhưng lại làm độ phức tạp tăng thêm do thiếu tính di động và tiêu chuẩn hóa giữa các hệ thống
- reStructuredText, AsciiDoc, DocBook, DITA cung cấp cấu trúc tường minh và semantic markup để tăng khả năng tái sử dụng và khả năng được máy diễn giải
- Với tài liệu nhỏ, Markdown là đủ, nhưng để quản lý tài liệu quy mô lớn, đa kênh, cần chuyển sang các định dạng có cấu trúc
Giới hạn về cấu trúc của Markdown
- Markdown có cú pháp đơn giản, dễ đọc với con người, cho phép tạo tài liệu đẹp mắt trên GitHub hoặc các trang web tĩnh
- Tuy nhiên, nó không mô tả được ý nghĩa của nội dung, nên thiếu thông tin cấu trúc để máy có thể hiểu được
- Công cụ tìm kiếm, LLM, IDE, AI agent... đều tận dụng cấu trúc ngữ nghĩa của tài liệu, nhưng Markdown chỉ tạo ra số lượng giới hạn các thẻ HTML
- Markdown gây ra vấn đề thiếu nhất quán khi tái sử dụng hoặc tích hợp nội dung do khác biệt cú pháp giữa các nền tảng
- Kết quả là Markdown chỉ là một định dạng ở mức mẫu số chung tối thiểu, không phù hợp cho quản lý tài liệu phức tạp
Vấn đề kiểu ngầm định của Markdown
- Markdown là một định dạng không có schema hay định nghĩa kiểu tường minh, nên cùng một tiêu đề hay danh sách có thể mang ý nghĩa khác nhau tùy theo ngữ cảnh
- Có nhiều biến thể Markdown (flavor) khác nhau, nên xảy ra khác biệt khi render giữa các công cụ
- Ví dụ: công cụ này hỗ trợ footnote, nhưng công cụ khác lại bỏ qua
- MDX mở rộng khả năng biểu đạt bằng cách chèn component React, nhưng tính di động kém do vấn đề tương thích giữa các hệ thống
- Những phần mở rộng này là nỗ lực để bù đắp giới hạn của Markdown, nhưng rốt cuộc chỉ là giải pháp chắp vá tạm thời chưa được tiêu chuẩn hóa
Tầm quan trọng của semantic markup
- Semantic markup mô tả ý nghĩa của nội dung thay vì hình thức của nó
- Ví dụ: “bước (step)” và “mục trong danh sách” có thể trông giống nhau về mặt thị giác nhưng khác nhau về ý nghĩa
- HTML5 đã đưa vào các thẻ dựa trên ngữ nghĩa như
<section>,<article>,<aside>để tăng cường khả năng biểu đạt cấu trúc - Các lợi ích cốt lõi của semantic markup
- Chuyển đổi và tái sử dụng: có thể chuyển cùng một nội dung sang nhiều định dạng như HTML, PDF, ePub
- Khả năng được máy diễn giải: LLM hoặc agent có thể nhận diện cấu trúc rõ ràng để đưa ra phản hồi chính xác hơn
- Markdown không cung cấp được loại thông tin cấu trúc này, nên xảy ra mất mát thông tin khi hậu xử lý hoặc chuyển đổi
So sánh các định dạng thay thế
- reStructuredText
- Là định dạng được dùng trong Sphinx của hệ sinh thái Python, biểu đạt ý nghĩa cấu trúc thông qua directive và role
- Hỗ trợ các phần tử cấu trúc tường minh như code block, note, tham chiếu chéo (
:ref:) - Phù hợp với tài liệu kỹ thuật quy mô lớn và hỗ trợ tạo HTML lẫn PDF
- AsciiDoc
- Là định dạng văn bản ngữ nghĩa cung cấp attribute, conditional content, và tính năng include
- Hỗ trợ cách biểu đạt chuyên cho tài liệu kỹ thuật như NOTE, WARNING, thành phần UI, cách ghi phím tắt
- Có thể chuyển sang HTML, PDF, ePub, DocBook... thông qua AsciiDoctor
- DocBook (XML)
- Là mô hình dựa trên XML cho xuất bản kỹ thuật, cung cấp hệ thống thẻ có ngữ nghĩa như
<command>,<note>,<xref> - Bao gồm các thẻ cần thiết cho tài liệu chuyên môn như bảng thuật ngữ, chỉ mục, thành phần UI, tên hàm
- Có thể chuyển sang nhiều định dạng đầu ra khác nhau thông qua stylesheet XSLT
- Có lợi cho kiểm tra cấu trúc tài liệu quy mô lớn và tạo chỉ mục
- Là mô hình dựa trên XML cho xuất bản kỹ thuật, cung cấp hệ thống thẻ có ngữ nghĩa như
- DITA (Darwin Information Typing Architecture)
- Là cấu trúc dựa trên XML dạng mô-đun được dùng như tiêu chuẩn tài liệu kỹ thuật doanh nghiệp
- Là kiến trúc XML dựa trên topic, định nghĩa rõ ràng cấu trúc thủ tục như
<task>,<step> - Được dùng như tiêu chuẩn quản lý tài liệu doanh nghiệp cho tái sử dụng nội dung (conref), lọc và xuất bản đa kênh
- Hỗ trợ tự động hóa render và chuyển đổi thông qua DITA Open Toolkit
Vì sao XML trông có vẻ bất tiện nhưng vẫn cần thiết
- Markdown tuy nhẹ, nhưng là một giải pháp tạm thời thiếu cấu trúc, tiêu chuẩn và tính nhất quán
- Nếu bạn đang làm Markdown phức tạp thêm bằng MDX, plugin và script tùy biến,
thì về lâu dài, việc áp dụng hẳn một định dạng có cấu trúc sẽ ổn định hơn
Vậy nên làm gì?
- Với tài liệu quy mô nhỏ như README hay tài liệu dùng một lần, Markdown là đủ; nhưng với tài liệu quy mô lớn, có tái sử dụng, đa kênh, reStructuredText, AsciiDoc, DocBook, DITA phù hợp hơn
- Nếu cần tài liệu hoạch định, tài liệu cho developer, tái sử dụng, quản lý quy mô lớn, hãy cân nhắc theo thứ tự reST/AsciiDoc → DocBook/DITA
- Cách tiếp cận hợp lý là dùng định dạng có cấu trúc phong phú nhất làm nguồn, rồi chuyển sang Markdown khi cần
- Markdown hữu ích như định dạng đầu ra, nhưng nếu dùng làm nguồn chân lý duy nhất (source of truth) thì rất khó mở rộng về mặt cấu trúc
- Tối ưu nhất là đặt bản gốc ở định dạng giàu cấu trúc ngữ nghĩa, còn Markdown dùng cho đầu ra downstream
7 bình luận
rst có phải là định dạng dựa trên XML không? Tôi mới nghe lần đầu đấy. Bản tóm tắt này có vấn đề.
Có vẻ tiêu đề được viết như vậy vì trong phần tóm tắt, tác giả nói về tiêu chí lựa chọn khi gộp nó cùng các định dạng XML khác.
Tôi đã sửa lại cho khớp với nguyên văn.
Nếu cần thì dùng HTML trong Markdown rồi gắn thêm Mermaid vào cũng tạm ổn... nhưng vượt quá mức đó thì có vẻ lại thành công việc vì tài liệu, vì công việc làm tài liệu.
Con người vẫn phải được đặt lên trước AI. Đừng ăn cắp thứ tôi đã viết. Nói gì mà ngữ nghĩa chứ.
Nếu phải dùng cú pháp đặc biệt thì lại phát sinh thêm một đường cong học tập khác, bộ công cụ phân tích cú pháp chuyên dụng, trình xem, trình soạn thảo v.v., tất cả đều phải được hỗ trợ trơn tru mới khả thi.. đến mức đó thì có lẽ cứ dùng Google Docs hoặc Notion, vốn có thể kết nối mượt mà với hầu hết các dịch vụ AI, còn tốt hơn
Ý kiến trên Hacker News
Điểm cốt lõi của Markdown là mức độ được hỗ trợ rất rộng, điều mà các ngôn ngữ khác không có Hầu hết các lựa chọn thay thế đều cần công cụ riêng và không dùng được trong những môi trường đã hỗ trợ Markdown sẵn Ngay cả Google Docs cũng hỗ trợ dán Markdown như một tính năng ẩn Dù không hoàn hảo, ưu điểm là “có thể dùng ở mọi nơi” Cũng như HTML đơn giản hơn SGML nhưng trở thành tiêu chuẩn nhờ được trình duyệt hỗ trợ, Markdown cũng có thể phát triển theo thời gian Sự mơ hồ trong tiêu chuẩn hóa, thiếu tính năng, vấn đề tương thích... đều giống với thời kỳ HTML4 Thay vì thay thế hoàn toàn, tiến hóa dần dần có lẽ là con đường thực tế hơn
Markdown có thể chứa thẻ HTML ở bất kỳ đâu Tài liệu chính thức cũng nói rõ điều này Vì vậy những ràng buộc mà tác giả nêu ra thực tế không tồn tại
haythì chẳng còn lý do gì để dùng Markdown Nếu câu trả lời cuối cùng là “cứ dùng HTML đi”, thì lý do tồn tại của Markdown cũng biến mấtThời đại học, khi học vật lý, tôi đã viết luận văn bằng LaTeX Bên hóa học thì dùng Word, tiêu chuẩn khác nhau tùy lĩnh vực Phiên bản của TeX biểu thị mức độ hoàn thiện mục tiêu bằng cách tiến gần tới giá trị π Phiên bản hiện tại là 3.141592653, và đã được duy trì ổn định suốt 47 năm Xem wiki về TeX, giải thích về phiên bản π Với công cụ CLI thì định dạng manpage cũng hữu ích
Markdown giống như một sản phẩm khả dụng tối thiểu (MVP) Nó dễ học và vẫn dễ đọc ngay cả khi chưa được render Việc tạo PDF của tôi đã chuyển từ AsciiDoc sang Typst, và nó giải quyết được vấn đề khả năng truy cập Nhưng không có ngôn ngữ đánh dấu nào tự nó làm cho bài viết hay hơn Đổi bút không làm cho văn hay hơn
Giọng điệu của bài này là lập luận rằng “Markdown đang cản trở sự phát triển của LLM” Nhưng giả định rằng có thể tự động có được sự phong phú về ngữ nghĩa là thiếu thực tế Trong nhóm của tôi chẳng ai có thời gian làm việc đó, và Markdown là đủ dùng Giống như các cuộc thảo luận về semantic web, rốt cuộc vấn đề vẫn là ai sẽ quản lý dữ liệu
Tôi viết blog bằng Org-mode + Emacs Tôi đặc biệt thích khả năng liên kết các khối mã để có thể chạy chúng ngay trong tài liệu Tôi cũng từng thử các nền tảng như Blorgit, lazyblorg, nhưng cấu hình phiền phức nên cuối cùng tôi tự xuất ra HTML rồi dùng rsync để đẩy lên server Tôi dùng script Ruby để gắn chỉ mục rồi triển khai Nó giàu khả năng biểu đạt và tự nhiên hơn nhiều so với Markdown
Tôi phần nào đồng ý với nhận định “Markdown thiếu cấu trúc”, nhưng thấy cách tiếp cận nhị nguyên ở đây khá đáng tiếc Trước khi chọn định dạng, lẽ ra phải hiểu trước cấu trúc cần thiết là gì Vì vậy tôi vừa thấy hơi khó chịu vừa khó mà hoàn toàn đồng tình
Việc đưa DITA ra như một lựa chọn thay thế Markdown là lập luận chệch hướng hoàn toàn DITA là một hệ thống XML cho doanh nghiệp quy mô lớn, mục đích hoàn toàn khác với Markdown Nó chỉ phù hợp trong môi trường có hơn 5.000 người, dòng sản phẩm đa ngôn ngữ và tương tự Nếu đang ở hoàn cảnh dùng Markdown thì DITA chắc chắn không phù hợp Cả hai đều là phí thời gian
Tôi đã dùng Markdown hơn 10 năm và nó vẫn hoạt động tốt Lập luận trong bài cũng không hoàn toàn sai, nhưng đó không phải vấn đề mà người dùng Markdown đang cảm nhận Cần gì thì cứ dùng cái khác Dù vậy tiêu đề hay nên tôi đã đọc khoảng 5 phút
Thật lạ khi bài viết nhắc đến MyST như một dạng Markdown rồi lại lấy reStructuredText (rST) làm ví dụ Mục đích của MyST chính là thay thế rST Cú pháp mang phong cách Markdown, nhưng vẫn hỗ trợ đầy đủ ý nghĩa cấu trúc, directive, role, v.v. Có thảo luận liên quan trong issue của Sphinx
Dạo này thấy khá nhiều bài kiểu này.
Tệp văn bản, Markdown, rồi các định dạng có cấu trúc hơn.
Khi chuyển đổi như vậy thì không có gì là đáp án đúng tuyệt đối, chỉ cần dùng đúng định dạng vào đúng thời điểm thích hợp.
Và nếu lúc nào cũng cố làm mọi thứ trong một tệp duy nhất thì sẽ phát sinh vấn đề, nên việc phân loại và hệ thống hóa cho phù hợp với chủ đề là điều tất yếu.