Cách dùng pandoc để chuyển đổi file trên Linux

Bạn có thể sử dụng pandoc trên Linux để chuyển hơn 40 định dạng file khác nhau. Bạn cũng có thể sử dụng nó để tạo ra một hệ thống docs-as-code đơn giản bằng cách ghi lại vào Markdown, lưu bằng git và xuất ra dưới bất cứ định dạng nào được hỗ trợ.

Chuyển đổi định dạng văn bản và docs-as-code

Nếu bạn có một văn bản thuộc bất kì định dạng file nào mà pandoc có hỗ trợ, vẫn chuyển đổi format sẽ vô cùng đơn giản.

Sức mạnh thực sự của pandoc trở nên rõ ràng hơn khi bạn sử dụng nó như một nền tảng của hệ thống docs-as-code đơn giản. Tiền đề của docs-as-code là áp dụng một số kỹ thuật và nguyên tắc phát triển phần mềm và sử dụng chúng vào việc viết tài liệu, đặc biệt là cho các dự án phát triển chương trình máy tính. Bạn có thể áp dụng nó để phát triển bất kỳ loại tài liệu nào.

Cài đặt pandoc

Để cài đặt pandoc trên Ubuntu, dùng lệnh:

sudo apt-get install pandoc

Trên Fedora, dùng lệnh:

sudo dnf install pandoc

Trên Manjaro, dùng lệnh:

sudo pacman -Syu pandoc

Bạn có thể kiểm tra xem mình đã cài đặt phiên bản nào nào bằng cách sử dụng lựa chọn --version:

pandoc --version

Sử dụng pandoc không cần file

Nếu bạn sử dụng pandoc mà không có bất kỳ tùy chọn dòng lệnh nào, nó cũng chấp nhận văn bản đã nhập. Chỉ cần nhấn Ctrl + D để cho máy biết bạn đã gõ xong. pandoc muốn bạn nhập định dạng Markdown và nó tạo đầu ra bằng HTML.

Xem ví dụ dưới đây:

pandoc

Nhập một số dòng Markdown và nhấn tổ hợp phím Ctrl + D.

Ngay sau khi nhập, pandoc tạo ra HTML output tương đương.

Tuy nhiên, để sử dụng pandoc thật hữu ích, chúng ta thực sự cần sử dụng các tệp.

Markdown cơ bản

Markdown là một ngôn ngữ đánh dấu nhẹ, dành cho một số ký tự nhất định. Bạn có thể sử dụng trình soạn thảo văn bản đơn giản để tạo tệp Markdown.

Markdown có thể được đọc dễ dàng, vì không có các thẻ rườm rà trực quan để đánh lạc hướng khỏi văn bản. Định dạng trong tài liệu Markdown giống với định dạng mà nó đại diện. Dưới đây là một số điều cơ bản:

• Để in nghiêng, hãy đặt văn bản trong dấu hoa thị.
• Để in đậm, dùng hai dấu hoa thị.
• Tiêu đề được thể hiện bằng dấu số/dấu #. Văn bản được phân tách từ hàm # bởi một khoảng trắng. Sử dụng một hàm # cho tiêu đề cấp cao nhất, hai hàm cho cấp độ thứ hai, v.v.
• Để tạo danh sách dấu đầu dòng, bắt đầu mỗi dòng của danh sách bằng dấu hoa thị và chèn khoảng trắng trước văn bản.
• Để tạo danh sách được đánh số, hãy bắt đầu mỗi dòng bằng một chữ số theo sau là dấu chấm, sau đó chèn khoảng trắng trước văn bản.
• Để tạo siêu liên kết, hãy đặt tên của trang web trong ngoặc vuông ([]) và URL trong ngoặc đơn [()] như vậy.
• Để chèn hình ảnh, nhập dấu chấm than ngay trước dấu ngoặc (! []). Nhập bất kỳ văn bản thay thế cho hình ảnh trong ngoặc. Sau đó, đặt đường dẫn đến hình ảnh trong ngoặc đơn [()Ví dụ].

Chuyển đổi file

Chuyển đổi tập tin rất đơn giản. pandoc thường có thể tìm ra định dạng tệp mà bạn làm việc cùng.Ví dụ ở đây sẽ tạo một tệp HTML từ Markdown. Tùy chọn -o (đầu ra) cho pandoc biết tên của tệp mà chúng ta muốn tạo:

pandoc -o sample.html sample.md

Tệp Markdown mẫu, sample.md, chứa phần ngắn của Markdown được hiển thị trong hình bên dưới.

Một tệp có tên sample.html được tạo. Khi click đúp vào tệp, trình duyệt mặc định sẽ mở nó.

Bây giờ, tạo một văn bản Open Document Format mở được trong LibreOffice Writer:

pandoc -o sample.odt sample.md

Tệp ODT có cùng nội dung với tệp HTML.

Chỉ định định dạng của file

Các tùy chọn -f (from) và -t (to) được sử dụng để báo cho pandoc biết định dạng tệp nào bạn muốn chuyển đổi từ đâu sang đâu. Điều này có thể hữu ích nếu bạn làm việc với định dạng tệp mà chia sẻ phần mở rộng tệp với các định dạng liên quan khác. Ví dụ, cả TeX và LaTeX đều sử dụng extension “.tex”.

Tùy chọn -s (standalone) cũng được sử dụng để pandoc sẽ tạo ra tất cả phần mở đầu LaTeX cần thiết cho một tài liệu để trở thành một tài liệu LaTeX hoàn chỉnh, khép kín và được hình thành tốt. Nếu không có tùy chọn -s (standalone), đầu ra vẫn sẽ là LaTeX, có thể được đưa vào một tài liệu LaTeX khác, tuy nhiên nó sẽ phân tích đúng như một tài liệu LaTeX độc lập.

Gõ dòng lệnh sau:

pandoc -f markdown -t latex -s -o sample.tex sample.md

Nếu mở file mẫu sample.tex trong một trình soạn thảo văn bản, bạn sẽ thấy LaTeX được tạo. Nếu bạn có trình soạn thảo LaTeX, mở tệp TEX để xem bản xem trước về cách diễn giải các lệnh sắp chữ LaTeX. Thu nhỏ cửa sổ để vừa với hình ảnh bên dưới khiến màn hình trông chật chội, nhưng thực tế, nó vẫn chạy ổn.

Đây là trình soạn thảo LaTeX được gọi là Texmaker. Nếu muốn cài đặt, gõ lệnh sau vào Ubuntu:

sudo apt-get install texmaker

Trên Fedora, gõ lệnh sau:

sudo dnf install texmaker

Trên Manjaro, dùng lệnh:

sudo pacman -Syu texmaker

Chuyển đổi file với template

Với các template, bạn có thể ra lệnh mà pandoc sử dụng khi tạo tài liệu. Ví dụ: yêu cầu pandoc sử dụng các kiểu được xác định trong tệp Cascading Style Sheets (CSS) với tùy chọn --css.

Một file CSS nhỏ chứa văn bản đã được tạo ra bên dưới. Nó thay đổi khoảng cách trên và dưới của các cấp tiêu đề. Nó cũng thay đổi màu văn bản thành màu trắng và màu nền thành màu xanh lam:

h1 {
   color: #FFFFFF;
   background-color: #3C33FF;
   margin-top: 0px;
   margin-bottom: 1px;
 }

Lệnh đầy đủ ở đây:

pandoc -o sample.html -s --css sample.css sample.md

Một tùy chọn tinh chỉnh khác có sẵn khi làm việc với các tệp HTML bao gồm đánh dấu HTML trong tệp Markdown của bạn. Nó sẽ được chuyển qua tệp HTML vừa tạo dưới dạng đánh dấu HTML tiêu chuẩn.

Kỹ thuật này chỉ nên sử dụng khi đầu ra HTML. Nếu bạn làm việc với nhiều định dạng tệp, pandoc sẽ bỏ qua đánh dấu HTML cho các tệp không phải HTML và nó sẽ được chuyển cho các định dạng dưới dạng văn bản.

Chúng ta cũng có thể chỉ định kiểu nào được sử dụng khi tệp ODT được tạo. Mở một trang LibreOffice Writer trắng và điều chỉnh các kiểu tiêu đề, phông chữ cho phù hợp với nhu cầu của bạn. Ví dụ dưới thêm một tiêu đề và đánh dấu trang. Sau đó, lưu tài liệu của bạn dưới dạng “odt-template.odt”.

Bây giờ chúng ta có thể sử dụng template này làm mẫu với tùy chọn --reference-doc:

pandoc -o sample.odt --reference-doc=odt-template.odt sample.md

So sánh điều này với ví dụ ODT từ trước đó. Tài liệu này sử dụng một phông chữ khác, có các tiêu đề màu và số trang. Tuy nhiên, nó được tạo ra từ cùng một tập tin “sample.md” của file Markdown. 

Các mẫu template tham khảo có thể được sử dụng để chỉ ra các giai đoạn khác nhau trong quá trình sản xuất tài liệu.

Tạo file PDF

Theo mặc định, pandoc sử dụng công cụ LaTeX PDF để tạo file PDF. Cách dễ nhất là cài đặt trình soạn thảo LaTeX, chẳng hạn như Texmaker.

Vì Tex và LaTeX đều khá lớn nên nếu dung lượng ổ cứng của bạn không đủ hoặc bạn không bao giờ sử dụng TeX hoặc LaTeX, hãy tạo file ODT. Sau đó, bạn chỉ cần mở nó trong LibreOffice Writer và lưu nó dưới dạng PDF.

Docs-as-Code

Một vài lợi ích của việc sử dụng ngôn ngữ lập trình Markdown:

• Làm việc nhanh trong các tệp văn bản đơn giản. Nhiều trình soạn thảo, bao gồm gedit, Vim và Emacs, sử dụng highlight với văn bản Markdown.
• Bạn sẽ có timeline của tất cả các phiên bản tài liệu. Nếu lưu trữ tài liệu của mình trong một VCS, ví dụ như Git, bạn có thể dễ dàng thấy sự khác biệt giữa hai phiên bản của cùng một tệp. Tuy nhiên, điều này chỉ thực sự hoạt động khi các tệp ở dạng văn bản thuần túy, vì đây là cách VCS làm việc.
• Một VCS có thể ghi lại thời gian và người đã thực hiện bất kỳ thay đổi nào. Điều này đặc biệt hữu ích nếu bạn thường xuyên làm việc nhóm trong các dự án lớn. Nó cũng cung cấp một kho lưu trữ trung tâm cho các tài liệu. Có nhiều dịch vụ lưu trữ Git đám mây như GitHub, GitLab và BitBucket, tất cả đều có phiên bản miễn phí và trả phí.
• Bạn có thể tạo tài liệu của mình theo nhiều định dạng. Chỉ với một vài tập lệnh shell đơn giản, bạn có thể lấy các mẫu từ CSS và tài liệu tham khảo. Nếu bạn lưu trữ tài liệu của mình trong kho lưu trữ VCS tích hợp với nền tảng CI/CD, chúng có thể tạo tự động bất cứ khi nào phần mềm được phát triển.