mdBook - Công cụ dòng lệnh để tạo sách bằng Markdown

 (rust-lang.github.io)
4 điểm bởi GN⁺ 2023-07-01 | 1 bình luận | Chia sẻ qua WhatsApp
  • Khi cần phân phối tài liệu và hướng dẫn dưới dạng sách, mdBook 0.5.3 cung cấp quy trình viết dựa trên Markdown cùng đầu ra có thể điều hướng dễ dàng
  • Nhờ cú pháp Markdown gọn nhẹ và tìm kiếm tích hợp, người viết có thể tập trung vào nội dung hơn là định dạng
  • Thông qua tô sáng cú pháp cho khối mã và các tệp giao diện, có thể điều chỉnh khả năng đọc và định dạng đầu ra cần thiết cho tài liệu kỹ thuật
  • Preprocessor và backend cung cấp các điểm mở rộng cho cú pháp tùy chỉnh, chỉnh sửa nội dung và render nhiều định dạng đầu ra
  • Đây là công cụ được dùng trong các dự án Rust và cuốn The Rust Programming Language, nên có tính kết nối cao với hệ sinh thái tài liệu Rust

Các tính năng cơ bản cần có để làm sách Markdown

  • mdBook là công cụ dòng lệnh để tạo sách bằng Markdown
  • Phù hợp để tạo nội dung gọn gàng, dễ điều hướng như tài liệu sản phẩm, tài liệu API, hướng dẫn và tài liệu giảng dạy
  • Cung cấp đồng thời các tính năng hỗ trợ trải nghiệm viết và đọc
    • Có thể tập trung vào nội dung với cú pháp Markdown gọn nhẹ
    • Hỗ trợ tìm kiếm tích hợp trong sách
    • Áp dụng tô sáng cú pháp có màu cho khối mã của nhiều ngôn ngữ
    • Có thể tùy biến định dạng đầu ra bằng các tệp theme

Mở rộng và kết nối với hệ sinh thái Rust

  • Preprocessor có thể đảm nhiệm việc mở rộng cú pháp tùy chỉnh và chỉnh sửa nội dung
  • Có thể render ra nhiều định dạng đầu ra thông qua backend
  • mdBook được viết bằng Rust để đạt tốc độ, an toàn và tính đơn giản
  • Hỗ trợ tự động kiểm thử mẫu mã Rust

Các trường hợp sử dụng thực tế và cách đóng góp

  • Chính tài liệu của mdBook là một ví dụ về đầu ra được tạo bằng mdBook
  • Dự án ngôn ngữ lập trình Rust sử dụng mdBook, và cuốn The Rust Programming Language cũng là một trường hợp sử dụng
  • mdBook là dự án mã nguồn mở miễn phí
  • Mã nguồn và tài liệu của mdBook được phân phối theo giấy phép Mozilla Public License v2.0

Bài viết liên quan

1 bình luận

 
GN⁺ 2023-07-01
Ý kiến trên Hacker News

  • Tôi nhớ nền tảng này dùng các thư viện được host trên CDN thay vì bundle hoặc vendor thư viện. Vì vậy người dùng không chỉ bị ảnh hưởng bởi sự cố CDN mà còn bị lộ trước dữ liệu mà máy chủ đó thu thập
    Điều đáng tiếc hơn là cách dùng Highlight.js và MathJax ở frontend rất lãng phí. Mọi client đều phải tự parse và render cú pháp cùng LaTeX, rồi lặp lại cùng một công việc đó mỗi lần truy cập để có cùng kết quả. Tô sáng cú pháp có thể được xử lý ở thời điểm build và hầu như không có lý do gì cần JavaScript cho việc đó

    • Có vẻ MathJax được host trên CDN, còn CSS và các tệp JS khác được đặt cạnh tệp HTML
      Có lẽ họ chọn như vậy vì hỗ trợ MathJax là tùy chọn: https://rust-lang.github.io/mdBook/format/mathjax.html
      Tuy vậy, nhiều khả năng JS của MathJax lại tiếp tục tải thêm các tệp khác từ CDN, nên thật khó hiểu vì sao họ không đặt toàn bộ tệp MathJax cạnh HTML được tạo ra
    • Có vẻ đã có một PR đang mở liên quan đến việc này: https://github.com/rust-lang/mdBook/pull/1918

  • Những công cụ tài liệu/trang tĩnh được nhắc đến trong luồng này gồm Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook
    Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook

    • Tôi cũng đã dùng nimibook
      Đây là bản port của mdBook sang Nim, nhưng còn mở rộng thêm khả năng tạo nội dung tương tác bằng backend JavaScript của Nim. Tôi chưa trực tiếp dùng, nhưng thích ý tưởng có thể tạo các thành phần tương tác ở một nơi khi cần: https://pietroppeter.github.io/nimib/interactivity.html
    • Cũng khó có thể bỏ qua Sphinx. Quy trình làm việc của nó phù hợp với định dạng sách hơn là kiểu blog, diễn đàn hay chuỗi thảo luận
    • HackMD hỗ trợ ký pháp công thức và thường là lựa chọn khi cần tạo tài liệu Markdown có thể chia sẻ và cộng tác chỉnh sửa: https://hackmd.io/
    • Sẽ thật tuyệt nếu có bảng hoặc trang so sánh tính năng của những công cụ này. Tôi muốn so sánh tìm kiếm tích hợp, xuất PDF, xuất ePub, nhiều theme, và các tính năng khác
    • Còn có https://jupyterbook.org/en/stable/ nữa. Tôi đang đóng góp cho Jupyter Book.

  • Tôi đã dùng MdBook, Jekyll và MkDocs; MdBook trông rất mượt cho dự án mặc định nhưng lại cho cảm giác quá tối giản. Khi xem mã nguồn của một site MdBook mà tôi thích, tôi thấy có trường hợp đã mở rộng bằng mã Rust tùy biến
    Khuyến nghị của tôi là MkDocs là lựa chọn mặc định linh hoạt ở mức hợp lý, Jekyll phù hợp khi cần nhiều độ linh hoạt hơn như cho landing page hoặc blog, còn Antora dành cho khi bạn muốn tạo site tài liệu tốt nhất bằng cách gom tài liệu từ nhiều dự án và nhiều phiên bản, và sẵn sàng bỏ nhiều công sức. AsciiDoc có rất nhiều tính năng hữu ích cho việc viết tài liệu
    Hugo có vẻ linh hoạt như Jekyll, nhưng cần nhiều công sức hơn để chỉnh cho đúng ý, và sự khác biệt về cách hoạt động giữa các theme có vẻ quá lớn. Tôi từng định đổi sang theme khác vì theme đang dùng thiếu tính năng cần thiết, nhưng việc chuyển đổi không hề dễ nên cuối cùng đã bỏ cuộc. MdBook trông khá năng động nên có lẽ cuối cùng sẽ bắt kịp

    • Tôi là người dùng Jekyll lâu năm và vẫn thấy nó rất tuyệt cho blog, nhưng trong số các trình tạo static site cho site tài liệu thì Docusaurus là cái tôi thấy tốt nhất: https://docusaurus.io/
      Tôi đã trì hoãn rất lâu vì không muốn dùng công cụ dựa trên JavaScript, nhưng khi thử thì thấy bắt đầu rất dễ, rất nhanh, site mặc định đẹp và cũng dễ tùy biến. Hỗ trợ MDX cũng rất xuất sắc
    • Landing page của material mkdocs theme(https://squidfunk.github.io/mkdocs-material/) thực sự rất tinh tế. Nghĩ đến việc đây là theme cho một phần mềm riêng biệt thì lại càng ấn tượng
    • Với mảng khoa học và thống kê thì tôi thấy Quarto rất xuất sắc: https://quarto.org
    • Tôi mới nghe về Antora lần đầu, nhưng cách nó lắp ghép tài liệu từ nhiều kho lưu trữ và quản lý phiên bản bằng branch đúng là cách hoạt động tôi đang muốn. Tuy vậy, việc không dùng MDX là điều đáng tiếc vì tài liệu hiện có là sự kết hợp giữa Markdown và các component React tương tác
    • Tôi dùng MkDocs rất nhiều và rất thích nó
      Tôi cũng đang thử BookStack; nó gần với wiki hơn, nhưng lại tốt cho những người không quá rành kỹ thuật. Thông thường tôi chỉnh sửa dự án MkDocs trong VSCode và đặt trong kho Git, còn BookStack thì hoàn toàn dựa trên web

  • Trước đây tôi dùng GitBook để tạo til.secretGeek.net, nhưng theo thời gian nó ngày càng chậm, đến mức build site mất 45 phút, và các tính năng tôi dùng thì либо bị khai tử либо chuyển thành “premium”. Rốt cuộc đó chính là lúc bắt đầu enshittification
    Nếu bạn đang dùng một công cụ miễn phí trông quá tốt, thì chỉ cần chờ vài năm là khả năng cao nó sẽ hỏng. Cuối cùng tôi đã tự làm một trình tạo static site cực kỳ tối giản bằng .NET để nó lại build xong trong vài giây. Tôi không quảng bá cho người khác dùng, vì nếu nó nổi tiếng thì có lẽ chính tôi cũng sẽ phá hỏng nó theo đúng kiểu đó

  • Tôi đã dùng mdBook ở nhiều dự án, nhưng dạo gần đây thấy material for mkdocs dễ dùng hơn vì có nhiều tính năng sẵn hơn hẳn
    Ví dụ, tôi rất thích mục lục trang ở bên phải, và mdBook thiếu khá rõ tính năng này. Trong mdBook, có vẻ cách làm tiêu chuẩn là cấu trúc SUMMARY thật chi tiết và tách nội dung vốn có thể để trong một trang thành nhiều file nhỏ hơn

    • material for mkdocs đủ tốt để đáng công cài Python và thiết lập virtual environment
    • Tôi đã thích MkDocs khá lâu rồi. Nó giúp hoàn thành công việc với ít phiền toái nhất, có nhiều theme để chọn, và cũng tương đối dễ để tự tùy biến hoặc làm mới
    • Tôi dùng https://github.com/JorelAli/mdBook-pagetoc để có mục lục theo từng chương

  • Vài ngày trước tôi bắt đầu dùng mdBook để viết tài liệu cho một dự án nhỏ, và nó đúng là trình tạo trang tĩnh nhỏ gọn khớp chính xác với thứ tôi cần
    Tôi cũng đã dùng HUGO, nhưng so với mdBook thì nó có vẻ quá lớn và cồng kềnh. Hiện tại tôi chỉnh sửa tài liệu bằng Obsidian/VIM và khi push lên Gitea thì tài liệu công khai được tạo trong vòng chưa đến 1 phút

    • Tôi dùng Hugo với book theme(https://github.com/alex-shpak/hugo-book). Nếu chưa quen Hugo thì sẽ cần thời gian làm quen, nhưng sau đó bạn sẽ thấy thích sự linh hoạt mà Hugo cung cấp, như shortcode
      Với shortcode phù hợp, có thể tự động đánh số cho hình ảnh, công thức, v.v. Tôi cũng tò mò không biết mdBook có hỗ trợ tự động đánh số hay không. Nó cũng có mục lục bên phải, tag, khả năng chia trang thành các cột, và hỗ trợ KaTeX tốt. Có vẻ mdBook dùng MathJax, và việc triển khai thì dễ chỉ với push hoặc rsync
    • Gần đây tôi bắt đầu dùng phần mở rộng PlantUML, và nó giúp ích cho việc chèn sơ đồ kiến trúc vào tài liệu

  • Gần đây tôi bắt đầu từ từ chuyển nội dung mới từ .md sang .mdx để xem thử, và thấy khá mới mẻ. Điều khó chịu nhất ở Markdown là mỗi phương ngữ lại có những giới hạn khác nhau, và cách mở rộng các giới hạn đó cũng mỗi nơi một kiểu
    Tôi rất hài lòng với 80~90% của phương ngữ GitBook Markdown tiêu chuẩn, nhưng thỉnh thoảng lại cần đến bảng phức tạp, khối mã chỉ nhấn mạnh vài dòng mà vẫn giữ được tô sáng cú pháp, thanh trượt tương tác, máy tính nhúng trong tài liệu, hoặc một số dạng đồ thị hay biểu đồ nhất định. Tôi không rõ MDX sẽ hoạt động thế nào trong các nhóm lớn, nhưng với công việc cá nhân thì nó chắc chắn có vẻ là một cải tiến

    • Tôi mới nghe đến .mdx lần đầu và đã tìm [0]. Có vẻ tôi đã không theo kịp đầy đủ xu hướng tiêu chuẩn hóa frontend
      Sẽ tốt hơn nếu bỏ được các phương ngữ và có một cách tiếp cận phổ quát duy nhất, nhưng trong tài liệu lại viết rằng “MDX không bị ràng buộc với React và có thể dùng với Preact, Vue, Emotion, Theme UI, v.v., đồng thời hỗ trợ cả classic/automatic JSX runtime.” Đã có cả triển khai Svelte [1], nên tôi không chắc lần này đây có phải là một chiếc hộp Pandora tạo thêm các phương ngữ gắn với framework frontend hay không. Ngay bên trong .mdx cũng có thể phân hóa, và có thể còn không tương thích với .md
      [0] https://mdxjs.com/docs/what-is-mdx/
      [1] https://mdsvex.com/docs
    • Hoàn toàn đồng ý. Khi tôi phát hiện ra Mdsvex, cảm giác như cuộc đời thay đổi vậy: https://mdsvex.com
    • .mdx có thể dùng rất dễ với https://astro.build/. Astro là một meta-framework JavaScript, đồng thời theo đuổi cách tiếp cận ưu tiên trình tạo site tĩnh không gửi JS xuống client
      Có các theme sẵn để dùng, nhưng nếu là một web developer hiện đại thì tự làm cũng khá dễ

  • Tôi đã tạo KeenWrite, một công cụ miễn phí, mã nguồn mở, đa nền tảng để làm sách dựa trên Markdown: https://github.com/DaveJarvis/keenwrite
    KeenWrite gọi ConTeXt để dàn trang tài liệu, và trong chế độ xem trước thì dùng một nhánh KeenType cho việc dàn công thức. Có thể tạo PDF từ dòng lệnh. Cuốn sách tôi đang viết hiện tham chiếu đến nhiều biến được định nghĩa trong tệp ngoài từ phần thân, truyền các thuộc tính PDF bằng metadata, và có thể chỉ build một số chương bằng đối số chapters. Thư mục theme chứa các chỉ thị dàn trang như màu sắc, phông chữ, bố cục, chú thích, v.v.
    Kết quả mẫu: https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...

  • Tôi thắc mắc vì sao Markdown hay một định dạng tương tự lại không phải là định dạng mặc định cho sách, tài liệu và gần như mọi kiểu văn bản. Sau khi chuyển sang Typora vài năm trước, tôi hầu như không còn cần Word/Writer cho những gì tự viết, và chỉ mở chúng khi cần xem tài liệu người khác gửi
    Tôi cũng không thấy lý do rõ ràng nào khiến 90% số sách tôi đọc lại không nên ở định dạng Markdown. Tôi hiểu rằng để in sách giấy đẹp thì cần dàn trang, nhưng phần lớn văn bản được đọc trên máy tính hay điện thoại thông minh, hoặc được in trực tiếp từ MS/LibreOffice, vốn dĩ cũng không được làm dàn trang bài bản theo kiểu đó

    • Markdown là một định dạng lưu trữ khá nghèo nàn. Có CommonMark là tiêu chuẩn bán chính thức, nhưng thiếu tính năng nên đa số dùng các biến thể khác như GitHub Markdown, và cũng có nhiều ứng dụng tự mở rộng Markdown theo những cách không tương thích với nhau
      Có những lựa chọn tốt hơn như AsciiDoc, nhưng nó thiên về tài liệu hóa và không có được đà phát triển gần với Markdown. Xét việc Markdown là một định dạng ra đời tương đối muộn, có lẽ câu hỏi đúng hơn là vì sao sách lại phải là Markdown. Ưu điểm lớn nhất của Markdown so với các định dạng nhị phân hay dựa trên XML là có thể đọc được ở mức độ nào đó như văn bản thuần, nhưng với phần lớn nhà xuất bản và độc giả thì điều đó không quá quan trọng
    • Dàn trang sách có rất nhiều sự tinh tế và độ phức tạp mà người không được đào tạo khó nhận ra, và chỉ Markdown+CSS thì không đủ tinh vi để xử lý hết. HTML/CSS+JS về mặt kỹ thuật có thể làm được, nhưng vẫn tụt khá xa so với trình độ hiện đại của dàn trang số
      Đây cũng là một cái bẫy kỹ sư điển hình kiểu “tôi có thể làm tốt hơn”, nên không nên mặc định như vậy nếu chưa tìm hiểu. Dàn trang là một lĩnh vực lâu đời hơn rất nhiều so với các công cụ đang được bàn ở đây, và không nên vứt bỏ những hiểu biết cùng kỹ thuật giá trị đã tích lũy chỉ vì Markdown gần như đủ dùng cho một số mục đích
    • Tôi viết rất nhiều tài liệu trong công việc, và tôi thích cách làm việc với Markdown khi vừa nhìn nguồn vừa nhìn kết quả render. Khi đã quen cú pháp thì Markdown nhanh hơn hẳn các trình soạn thảo như Word, và đến mức việc chỉ tạo một danh sách trong trình soạn thảo văn bản cũng thấy phiền phức

  • mdBook dễ dùng, và tôi đặc biệt thích việc người dùng có thể chọn theme. Tôi chủ yếu dùng nó cho phiên bản online của ebook [0] và các tài liệu tuyển chọn [1][2]
    [0] https://github.com/learnbyexample/scripting_course#ebooks
    [1] https://learnbyexample.github.io/py_resources/
    [2] https://learnbyexample.github.io/curated_resources/