Công cụ chuyển đổi README sang PDF

Tệp README.md là một tài liệu Markdown giải thích về một dự án, kho lưu trữ, gói, ứng dụng, tập dữ liệu hoặc quy trình làm việc.

Các tệp README thường bao gồm:

• tiêu đề và tóm tắt dự án;
• hướng dẫn cài đặt;
• ví dụ sử dụng;
• các đoạn mã dòng lệnh;
• ví dụ cấu hình;
• danh sách tính năng;
• danh sách công việc;
• bảng;
• ảnh chụp màn hình;
• huy hiệu (badge);
• hướng dẫn đóng góp;
• thông tin giấy phép hoặc hỗ trợ;
• liên kết đến tài liệu và các bản phát hành.

Phần mở rộng .md có nghĩa là tệp được viết bằng Markdown. Việc chuyển đổi nó sang PDF tạo ra một tài liệu cố định trong khi vẫn bảo toàn nguồn Markdown làm phiên bản có thể chỉnh sửa.

Tệp PDF hữu ích khi README cần rời khỏi kho lưu trữ gốc của nó hoặc được xem xét như một tài liệu dạng trang.

Các lý do phổ biến bao gồm:

• chia sẻ tài liệu dự án với khách hàng hoặc bên liên quan;
• đính kèm một bản tóm tắt kỹ thuật vào email hoặc thẻ công việc (ticket);
• gửi tài liệu để xem xét hoặc phê duyệt;
• tạo một ảnh chụp nhanh ngoại tuyến của một kho lưu trữ tại một thời điểm cụ thể;
• in hướng dẫn thiết lập hoặc một tài liệu hướng dẫn vận hành;
• lưu trữ tài liệu phát hành;
• phân phối một README cho những độc giả không sử dụng GitHub;
• xem lại mã nguồn dài, phương trình, sơ đồ và các bảng trong một bố cục cố định.

README gốc nên vẫn là nguồn có thể bảo trì. Tạo lại tệp PDF sau khi README thay đổi.

SolConverter hỗ trợ các thành phần Markdown thường được sử dụng trong các tệp README.

Chúng bao gồm:

• Các tiêu đề ATX và Setext;
• văn bản đậm, nghiêng và gạch ngang;
• danh sách có thứ tự và không có thứ tự;
• danh sách lồng nhau;
• danh sách công việc GFM;
• khối trích dẫn;
• liên kết Markdown và tự động liên kết;
• mã nội dòng;
• các khối mã có hàng rào sử dụng dấu nháy ngược hoặc dấu ngã;
• nhãn ngôn ngữ của khối mã;
• bảng GFM với căn lề;
• bảng HTML thô an toàn;
• các phần details và summary;
• kbd, sub, sup, figure và figcaption;
• neo tiêu đề;
• YAML front matter ở đầu tệp nguồn.

Các hàng rào mã chứa ký hiệu đô la hoặc dấu phân tách giống LaTeX vẫn là mã nguồn thay vì bị diễn giải thành các phương trình.

Các tệp README thường chứa các lệnh cài đặt, tệp cấu hình, ví dụ API, biến môi trường và các đoạn mã nguồn.

SolConverter áp dụng tô sáng cú pháp với Highlight.js khi ngôn ngữ của khối mã được nhận dạng. Ngôn ngữ không được nhận dạng vẫn giữ nguyên nguồn ban đầu một cách an toàn.

Các khối mã sử dụng phông chữ đơn cách chuyên dụng và kiểu dáng in ấn giúp tách biệt chúng khỏi phần giải thích xung quanh. Mã nguồn vẫn giữ hướng từ trái sang phải ngay cả trong một README từ phải sang trái.

Một README kỹ thuật có thể chứa các công thức, ma trận, ký hiệu khoa học, biểu thức xác suất hoặc hóa học.

SolConverter hỗ trợ đầu ra MathJax SVG cho các dấu phân tách toán học Markdown phổ biến, môi trường phương trình AMS, Presentation MathML, Content MathML cơ bản và các biểu thức hóa học được viết bằng \ce{...}.

Toán học được hỗ trợ bao gồm:

• $...$ và \(...\) biểu thức nội dòng;
• $$...$$ và \[...\] biểu thức hiển thị;
• các môi trường phương trình và căn chỉnh;
• phân số, căn thức, tổng, tích phân, giới hạn và ma trận;
• các macro phạm vi tài liệu;
• các biểu thức cộng dài cần ngắt dòng.

Toán học được hiển thị dưới dạng SVG để giữ độ sắc nét trong PDF. Toán học không hợp lệ có thể tự động chuyển sang dự phòng cục bộ mà không dừng phần còn lại của README.

Các tệp README thường sử dụng sơ đồ để giải thích kiến trúc, trình tự, trạng thái, quy trình làm việc hoặc mối quan hệ thành phần.

Các khối Mermaid hợp lệ được hiển thị cục bộ dưới dạng SVG. ZenUML được hỗ trợ thông qua tích hợp Mermaid được đóng gói kèm. Các sơ đồ bị giới hạn trong chiều rộng trang khả dụng và được xử lý độc lập.

Nếu một sơ đồ không hợp lệ, công cụ chuyển đổi sẽ chèn một dự phòng với nguồn và tiếp tục hiển thị các phần còn lại.

PlantUML, Graphviz, D2, WaveDrom, BPMN, Nomnoml và TikZ đầy đủ hiện không được hỗ trợ và không nên được quảng cáo trên trang này.

Công cụ chuyển đổi hỗ trợ hình ảnh HTTP và HTTPS công cộng và hình ảnh dữ liệu base64 hợp lệ ở các định dạng PNG, GIF, JPEG, WebP và SVG.

Hình ảnh được chia tỷ lệ để vừa với trang và giữ nguyên tỷ lệ khung hình. Các hình, chú thích, văn bản thay thế (alt), tiêu đề, kích thước an toàn và căn lề có thể được giữ lại.

Tuy nhiên, nhiều README của kho lưu trữ sử dụng các đường dẫn tương đối như:

./images/screenshot.png
docs/architecture.svg
../assets/demo.gif

Quy trình tải lên hiện tại không đóng gói thư mục kho lưu trữ hoặc tự động giải quyết các tài sản tương đối đó. Hãy chuyển đổi chúng thành URL hình ảnh công cộng hoặc hình ảnh dữ liệu base64 được hỗ trợ trước khi tạo PDF.

Huy hiệu thường sử dụng URL hình ảnh công cộng và có thể hiển thị khi máy chủ hình ảnh có thể truy cập công khai. Nếu một huy hiệu hoặc hình ảnh không thể tải được, SolConverter sẽ chèn một trình giữ chỗ cục bộ và tiếp tục chuyển đổi.

Các liên kết Markdown bên trong một README có thể là liên kết tuyệt đối, liên kết tương đối của kho lưu trữ hoặc liên kết phân đoạn trang.

Các liên kết HTTP và HTTPS tuyệt đối vẫn có ý nghĩa bên ngoài kho lưu trữ. Các liên kết tương đối như ./docs/setup.md hoặc ../CONTRIBUTING.md có thể không trỏ đến một điểm đến hữu ích sau khi README trở thành một tệp PDF độc lập.

Trước khi chia sẻ tệp PDF:

• thay thế các liên kết tương đối quan trọng bằng các URL tuyệt đối công khai;
• viết ra các hướng dẫn quan trọng thay vì chỉ dựa vào các tệp được liên kết;
• xác minh các liên kết tiêu đề sau khi hiển thị;
• kiểm tra xem tài liệu có còn dễ hiểu mà không cần điều hướng kho lưu trữ hay không;
• bao gồm thông tin phiên bản hoặc bản phát hành khi tệp PDF được dự định làm tài liệu lưu trữ.

Một GitHub README vẫn là một tệp Markdown, nhưng GitHub có thể thêm ngữ cảnh kho lưu trữ không có trong chính tệp được tải lên.

Tệp PDF có thể bảo tồn các cấu trúc GFM được hỗ trợ như bảng, danh sách công việc, mã khối có hàng rào, tự động liên kết và tiêu đề. Nó cũng có thể hiển thị các biểu thức MathJax và sơ đồ Mermaid được hỗ trợ.

Công cụ chuyển đổi không tái tạo mọi thành phần giao diện của GitHub. Các tab kho lưu trữ, số lượng lỗi (issues), các thành phần phát hành (widgets), trình chọn nhánh, thẻ được tạo động và các thành phần trang GitHub khác không phải là một phần của nguồn Markdown.

Để có tệp PDF độc lập sạch nhất, hãy đảm bảo README bao gồm nhận diện dự án, ngữ cảnh phiên bản và các liên kết quan trọng ngay trong chính tài liệu.

Một tài liệu README PDF có thể hoạt động như một bản bàn giao kỹ thuật ngắn gọn khi người đọc cần:

• tổng quan dự án;
• các bước cài đặt và thiết lập;
• ví dụ về các lệnh;
• yêu cầu cấu hình;
• sơ đồ kiến trúc;
• ví dụ API;
• ghi chú vận hành;
• hướng dẫn khắc phục sự cố;
• chi tiết đóng góp hoặc hỗ trợ.

Đối với các bộ tài liệu lớn, hãy coi README là tài liệu lối vào thay vì ép buộc mọi hướng dẫn vào một tệp duy nhất. Một tệp PDF được tạo từ một README rất dài vẫn có thể hữu ích, nhưng các tài liệu riêng biệt có thể dễ bảo trì và điều hướng hơn.

Các kho lưu trữ thay đổi theo thời gian. Chuyển đổi README sang PDF tạo ra một ảnh chụp nhanh có thể đọc được liên kết với một bản phát hành, đợt phân phối, đợt đánh giá hoặc cột mốc.

Trước khi lưu trữ:

1. add the project or package version;
2. bao gồm ngày tháng liên quan hoặc mã định danh phát hành;
3. xác minh lệnh và các ví dụ cấu hình;
4. thay thế các liên kết tạm thời;
5. xem lại hình ảnh, sơ đồ và phương trình;
6. tạo và kiểm tra tệp PDF cuối cùng;
7. lưu trữ tệp PDF bên cạnh hồ sơ phát hành.

Tệp PDF được tạo ra là một ảnh chụp nhanh, không phải là sự thay thế cho README được kiểm soát nguồn.

Các tệp README có thể chứa HTML thô, URL hình ảnh từ xa và các khối bị lỗi định dạng.

SolConverter khử trùng HTML hiển thị, loại bỏ các tập lệnh và trình xử lý sự kiện, từ chối các URL không an toàn, giới hạn HTML thô trong một danh sách cho phép, giới hạn nhịp bảng, áp dụng chính sách bảo mật nội dung hạn chế và chặn các yêu cầu trình duyệt bên ngoài chính sách hình ảnh được phép.

Các tệp cục bộ, đích đến localhost, địa chỉ IP riêng, URL javascript: và các lược đồ tài nguyên không được hỗ trợ bị chặn. Các hình ảnh, phương trình và sơ đồ không hợp lệ được xử lý cục bộ nếu có thể để phần còn lại của README có thể tiếp tục hiển thị.

SolConverter áp dụng một bố cục tài liệu nhất quán cho các tệp README.

Biểu mẫu web hiện tại sử dụng:

• Khổ trang A4;
• hướng dọc;
• lề được quản lý cho đầu ra dễ đọc;
• đánh số trang trang hiện tại / tổng số trang;
• tiêu đề đầu ra dựa trên tên tệp README;
• in hình nền.

Bố cục dọc được thiết kế để đọc thông thường. Hãy luôn xem trước các bảng rộng và mã nguồn trước khi tải xuống.

Hãy sử dụng trang tập trung vào README này khi nguồn là một README dự án và bạn cần hướng dẫn về hàng rào mã, cấu trúc GFM, huy hiệu, hình ảnh tương đối của kho lưu trữ và các liên kết kho lưu trữ.

Sử dụng công cụ chuyển đổi Markdown sang PDF chính cho các báo cáo, tài liệu toán học, ghi chú kỹ thuật, đề xuất, tài liệu đa ngôn ngữ và các tệp .md nói chung.

Cả hai trang đều sử dụng cùng một khả năng chuyển đổi cốt lõi, nhưng chúng phục vụ các tác vụ người dùng khác nhau và cung cấp hướng dẫn chuẩn bị khác nhau.

• Chuyển đổi bất kỳ tệp Markdown nào sang PDF
• Chuyển đổi PDF sang Markdown
• Chuyển đổi HTML sang Markdown
• Chuyển đổi Word sang Markdown
• Duyệt tất cả các công cụ chuyển đổi sang Markdown