Trình Tạo Bảng Markdown

Về bảng Markdown

Bảng Markdown sử dụng dấu gạch đứng (|) và dấu gạch ngang (-) để tạo dữ liệu dạng bảng có cấu trúc trong văn bản thuần. Chúng được hỗ trợ bởi GitHub, GitLab, Reddit và hầu hết các trình kết xuất Markdown. Dòng căn lề sử dụng dấu hai chấm để chỉ định căn trái, giữa hoặc phải cho mỗi cột.

Viết bảng Markdown bằng tay có thể tẻ nhạt và dễ gây lỗi. Trình soạn thảo trực quan này cho phép bạn nhập dữ liệu vào lưới dạng bảng tính và tạo Markdown được định dạng đúng trong thời gian thực. Tất cả quá trình xử lý diễn ra trong trình duyệt của bạn.

Cú pháp bảng pipe, một cách máy móc

Một bảng GFM bao gồm ba phần: hàng tiêu đề với các ô được phân tách bằng pipe (|), hàng phân cách ngay bên dưới sử dụng dấu gạch ngang (---) cho mỗi cột, và không hoặc nhiều hàng dữ liệu với cùng cấu trúc phân tách bằng pipe. Pipe ở đầu và cuối mỗi hàng là tùy chọn nhưng theo quy ước được bao gồm để dễ đọc. Căn chỉnh cột được chỉ định bởi dấu hai chấm trong hàng phân cách: :--- cho căn trái (mặc định), :---: cho căn giữa, ---: cho căn phải. Bảng tối thiểu khả dụng trông như thế này trong nguồn: | Tiêu đề | Tiêu đề | ở dòng 1, | --- | --- | ở dòng 2, | Ô | Ô | từ dòng 3 trở đi. Nội dung ô có thể bao gồm bất kỳ định dạng Markdown inline nào (in đậm, in nghiêng, liên kết, code span, hình ảnh) nhưng không thể bao gồm các phần tử cấp block (danh sách, khối code, blockquote). Ngắt dòng trong một ô cần được mã hóa dưới dạng thẻ <br> thay vì ngắt dòng nguyên văn, vì ngắt dòng nguyên văn sẽ phá vỡ cấu trúc bảng. Ký tự pipe bên trong nội dung ô phải được escape dưới dạng \|, nếu không parser sẽ coi chúng là dấu phân cách cột và số cột của hàng sẽ sai. Hầu hết parser dung nạp chiều rộng cột không thẳng hàng; nguồn | a | b | và | aaa | b | render giống hệt nhau, mặc dù cái sau trông "đúng" hơn trong nguồn. Công cụ này luôn xuất ra nguồn có chiều rộng thẳng hàng để dễ đọc, nhưng render giống như nguồn nhỏ gọn.

Nơi bảng render và nơi không

Render chính xác: GitHub (issue, pull request, README, trang wiki, thảo luận, code review, bình luận ở bất kỳ đâu), GitLab (cùng các bề mặt), Bitbucket, Stack Overflow, Reddit (khi GFM được kích hoạt trong subreddit, là hầu hết chúng), Discord (chỉ trong ngữ cảnh code-block, bảng GFM đầy đủ không render trong tin nhắn chat nhưng markdown-it xử lý chúng trong bề mặt docs), Notion (với nhập bảng riêng), Obsidian, Logseq, Bear, hầu hết các trình tạo trang tĩnh (Hugo, Jekyll, Eleventy, Astro với plugin remark-gfm, Next.js MDX), preview của VS Code, GitHub Pages, Read the Docs (tùy thuộc vào cấu hình). Không render chính xác: CommonMark nghiêm ngặt (Pandoc với reader commonmark và không có extension, parser Discount C không có cờ pipe-table), Slack (render tập con Markdown nhưng không bảng), hầu hết các email client (HTML được render trong email về mặt cấu trúc thì ổn nhưng có inline-styled, không phải Markdown), các cài đặt WordPress cũ hơn không có plugin Markdown. Quy tắc chung: nếu đích đến của bạn là nền tảng định hướng developer (gia đình GitHub, tài liệu kỹ thuật), bảng GFM hoạt động. Nếu đích đến của bạn là nền tảng đối tượng chung (Slack, email, Twitter), giả định rằng bảng sẽ không render và hoặc pre-render thành hình ảnh hoặc viết lại dưới dạng danh sách.

Cú pháp bảng Markdown thay thế

Định dạng bảng pipe thống trị nhờ phạm vi tiếp cận của GitHub, nhưng đó không phải là cú pháp bảng Markdown duy nhất. Bảng đơn giản Pandoc sử dụng dấu phân cách dòng trống-và-gạch ngang và căn chỉnh cột theo vị trí trực quan thay vì pipe, dễ đọc hơn nhiều cho các bảng hẹp nhưng khó viết bằng tay hơn. Bảng đa dòng Pandoc hỗ trợ các ô trải dài nhiều dòng, quan trọng cho nội dung mô tả dài không phù hợp với một hàng. Bảng grid Pandoc sử dụng các viền ASCII-art (+---+---+) trông đau đớn khi duy trì bằng tay nhưng dễ cho các công cụ xuất ra. reStructuredText (Sphinx) sử dụng bảng grid độc quyền, tài liệu mọi dự án Python đều được viết theo cách này. AsciiDoc sử dụng cú pháp tiền tố pipe khác (|===) được tối ưu cho việc viết sách kỹ thuật. HTML trong Markdown luôn có sẵn như cửa thoát: bất kỳ trình xử lý Markdown nào cũng đi qua HTML thô, vì vậy khi bảng pipe không đủ bạn có thể thả vào một <table> thực sự với phạm vi hàng/cột đầy đủ, markup ngữ nghĩa và styling CSS. Cú pháp bảng pipe mà công cụ này tạo ra là kiểu GFM, lựa chọn tương thích nhất cho hệ sinh thái developer hiện đại.

Sử dụng phổ biến

• Tệp README GitHub. Bảng so sánh ("thư viện của chúng tôi vs các lựa chọn thay thế"), ma trận tính năng, danh sách phiên bản được hỗ trợ, danh sách người đóng góp, thẻ tham chiếu lệnh. Có lẽ là việc sử dụng sản xuất phổ biến nhất duy nhất của bảng GFM.
• Tài liệu và wiki. Bảng tham chiếu API (tên tham số / kiểu / mô tả / mặc định), bảng tùy chọn cấu hình, tham chiếu mã lỗi, ma trận dịch thuật ngôn ngữ. Read the Docs, MkDocs, Docusaurus, GitBook đều hỗ trợ bảng GFM.
• Bài đăng blog so sánh. Các bài viết "Framework X vs Framework Y", so sánh thông số phần cứng, phân tích cấp giá. Định dạng bảng pipe dễ đọc hơn nhiều so với các đoạn văn ad-hoc và render sạch sẽ trên Medium, dev.to, Substack và các blog cá nhân.
• Trang giá. Bảng cấp SaaS (Free / Pro / Enterprise qua các hàng tính năng) hoạt động tốt ở dạng bảng pipe cho các mockup phiên bản nháp nhanh trước khi các nhà thiết kế thương mại thực hiện phiên bản HTML hoàn thiện.
• Template issue GitHub. Các template báo cáo lỗi thường bao gồm các bước tái tạo ở dạng bảng (Bước / Mong đợi / Thực tế / Screenshot). Bảng trạng thái bảng dự án để theo dõi tiến độ sprint.
• Ghi chú cuộc họp và kế hoạch dự án. Bảng mục hành động (Chủ sở hữu / Hành động / Ngày đến hạn / Trạng thái) trong các tài liệu ghi chú chia sẻ. Nhật ký quyết định. Sổ đăng ký rủi ro.
• Nhập CSV. Nhiều trình tạo bảng cung cấp nhập CSV-sang-Markdown, dán CSV, nhận bảng Markdown. Ngược lại (Markdown sang CSV) cũng phổ biến khi trích xuất dữ liệu có cấu trúc từ tài liệu trở lại định dạng bảng tính.

Vấn đề chiều rộng và các ràng buộc khác

Bảng pipe có một số hạn chế vốn có đáng biết. Chiều rộng cột bị ràng buộc bởi nội dung ô dài nhất, một URL dài hoặc đoạn văn mô tả trong một ô buộc toàn bộ cột rộng, có thể tạo ra các bảng cồng kềnh không phù hợp với chiều rộng trang tài liệu chuẩn. Cách khắc phục là cắt nội dung dài (liên kết đến nơi khác để biết chi tiết) hoặc sử dụng HTML inline nếu bạn cần ô có thể bao bọc. Không có phạm vi hàng hoặc cột, mỗi ô chiếm chính xác một hàng và một cột. Các bảng phức tạp với các ô được hợp nhất cần HTML <table> thực sự với các thuộc tính rowspan / colspan. Không có bảng lồng nhau, bạn không thể đặt một bảng bên trong một ô bảng khác trong Markdown. Không có nội dung cấp block trong các ô, không có danh sách, không có khối code, không có blockquote bên trong một ô. Nội dung inline (in đậm, in nghiêng, code span, liên kết, hình ảnh) thì ổn nhưng bất kỳ thứ gì đa dòng đều cần các thẻ <br>. Hàng tiêu đề là bắt buộc trong GFM, không có cú pháp bảng không tiêu đề. Nếu bạn muốn một bảng không có tiêu đề hiển thị, hãy để trống các ô tiêu đề nhưng hàng vẫn phải có mặt. Căn chỉnh áp dụng mỗi cột cho toàn bộ cột, bạn không thể có căn chỉnh khác nhau cho các ô khác nhau trong cùng một cột. Đối với các layout bảng tinh vi vượt quá các ràng buộc này, công cụ phù hợp là HTML trong nguồn Markdown của bạn, không phải Markdown chính nó.

Chuyển đổi CSV ↔ Markdown

Hầu hết dữ liệu dạng bảng thực tế sống trong các tệp CSV (xuất bảng tính, phản hồi API, đầu ra phân tích log), chuyển đổi sang và từ Markdown là một quy trình làm việc phổ biến. CSV → Markdown: parse CSV (xử lý các trường được trích dẫn với dấu phẩy được nhúng, các trích dẫn được escape, ngắt dòng trong các trường), sau đó định dạng mỗi hàng là | giá trị | giá trị | với các hàng tiêu đề và phân cách thích hợp. Hầu hết các trình tạo bảng bao gồm cái này cung cấp nhập CSV; đối với chuyển đổi một lần, bạn cũng có thể sử dụng công cụ dòng lệnh csvlook của csvkit tạo ra đầu ra định dạng pipe tương tự. Markdown → CSV: parse bảng GFM trở lại thành các hàng và cột, sau đó xuất CSV với trích dẫn phù hợp. Hữu ích khi trích xuất dữ liệu có cấu trúc từ tài liệu trở lại dạng bảng tính để phân tích. Hướng Markdown-sang-CSV được cung cấp bởi các công cụ như pandoc (với sự kết hợp reader/writer phù hợp), tableconvert.com, và các tiện ích dòng lệnh khác nhau. Chuyến đi vòng có mất mát theo một hướng, định dạng (in đậm, liên kết, hình ảnh) chỉ tồn tại nguyên vẹn qua bước CSV nếu bạn viết nội dung ô CSV dưới dạng văn bản Markdown thô và xử lý kết quả như Markdown lần nữa.

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

Bảng dường như không phải là dữ liệu nhạy cảm, nhưng nội dung của bảng thường là. Kế hoạch dự án chứa các quyết định nhân sự và các tính năng chưa được công bố. Bảng giá chứa thông tin thương mại. Các bảng so sánh trong các bài đăng blog chưa xuất bản tiết lộ vị trí biên tập. Các mục hành động ghi chú cuộc họp chứa thông tin phân công và trách nhiệm giải trình. Các trình tạo bảng phía máy chủ tải dữ liệu của bạn lên bên thứ ba nơi nó nằm trong logs. Công cụ này chạy hoàn toàn trong trình duyệt của bạn qua JavaScript, xác minh trong tab Network của DevTools khi bạn chỉnh sửa các ô, hoặc đưa trang offline (chế độ máy bay) sau khi tải và trình chỉnh sửa vẫn hoạt động. An toàn cho các bản nháp tài liệu chưa được công bố, kế hoạch dự án nội bộ, bảng so sánh cho các bài đăng blog chưa được công bố, hoặc bất kỳ nội dung bảng nào 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

Cú pháp bảng Markdown nào được tạo ra?

Nó tạo ra cú pháp tiêu chuẩn GFM (GitHub Flavored Markdown) với dấu gạch đứng, một dòng phân cách dấu gạch ngang và dấu hai chấm tùy chọn cho căn lề. Cú pháp này hoạt động trên GitHub, GitLab, Reddit, Jekyll, Hugo và hầu hết các bộ xử lý Markdown.

Làm thế nào để đặt căn lề cột?

Nhấp các nút L (trái), C (giữa) hoặc R (phải) bên dưới mỗi tiêu đề cột. Căn trái dùng :---, giữa :---: và phải ---: trong dòng phân cách.

Tôi có thể nhập từ CSV hoặc dán từ bảng tính không?

Nhập CSV nằm trong roadmap. Hiện tại, dán-từ-Excel/Google Sheets thường hoạt động vì hầu hết các ứng dụng bảng tính đặt dữ liệu phân tách bằng tab vào clipboard, mà bạn có thể dán vào các ô riêng lẻ. Để nhập CSV hàng loạt mà không dán thủ công, các công cụ dòng lệnh như csvlook của csvkit tạo ra đầu ra bảng GFM tương tự, hoặc pandoc có thể chuyển đổi CSV sang Markdown trực tiếp với pandoc --from csv --to gfm input.csv.

Còn các ô được hợp nhất, bảng lồng nhau, hoặc nội dung block trong các ô thì sao?

Bảng pipe GFM không hỗ trợ những điều này. Mỗi ô chiếm chính xác một hàng và một cột; không có rowspan hoặc colspan. Không có bảng lồng nhau. Không có nội dung cấp block (danh sách, khối code, blockquote) bên trong một ô, chỉ có nội dung inline (in đậm, in nghiêng, code span, liên kết, hình ảnh, ngắt dòng qua <br>). Đối với các layout bảng tinh vi vượt quá các ràng buộc này, hãy nhúng HTML <table> thô trực tiếp vào nguồn Markdown của bạn, mọi trình xử lý Markdown đều đi qua HTML không thay đổi. Sự đánh đổi là nguồn trở nên khó đọc và chỉnh sửa bằng tay hơn nhiều.

Có giới hạn hàng hoặc cột không?

Bạn có thể có tối đa 20 cột và 100 hàng. Với hầu hết tài liệu và tệp README, điều này là quá đủ. Bảng cập nhật trong thời gian thực khi bạn gõ.

Nội dung bảng của tôi có được gửi đi đâu không?

Không. Quá trình tạo chạy hoàn toàn trong trình duyệt của bạn qua JavaScript. Các ô bạn chỉnh sửa và đầu ra 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à trình chỉnh sửa vẫn hoạt động. An toàn cho các bản nháp tài liệu chưa được công bố, kế hoạch dự án nội bộ, bảng so sánh giá chưa được công bố, hoặc bất kỳ nội dung dạng bảng 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