用Pandoc和Latex從Markdown創建PDF

核心要點

本文作者Chris Ward介紹瞭如何使用Pandoc和LaTeX將Markdown文件轉換為PDF，用於其開源棋盤遊戲Chip Shop。遊戲組件使用Markdown編寫，遊戲網站也由這些文件生成。

Pandoc（一個開源標記轉換工具）和LaTeX（一個文檔聲明和佈局系統）用於從Markdown文件生成PDF。儘管功能強大，但它們無法將多個PDF組合到一頁上，因此Ward使用了命令行工具PDFJam來滿足此需求。

作者提供了詳細的指南，介紹如何安裝必要的依賴項（Markdown、Jekyll、Pandoc、LaTeX、PDFJam），並逐步介紹了構建過程，包括從Markdown生成PDF、創建LaTeX文件以及使用PDFJam將卡片組合到一頁上。

作者理想的工作流程是在生成網站的同時生成PDF文件，而不是在訪問者請求時生成文件。這種方法還允許PDF卡片版本與HTML頁面看起來不同，而無需使用複雜的CSS規則。

如果您閱讀過我在SitePoint或其他地方發表的一些文章，您可能知道我正在開發一款棋盤遊戲。這款名為Chip Shop的遊戲，讓您可以在20世紀80年代的美國經營一家電腦公司。

作為項目的一部分，我嘗試盡可能地將整個遊戲開源。經過幾次嘗試後，我決定使用Markdown作為大部分遊戲組件（尤其是卡片和說明書）的基本框架。

由於遊戲網站使用Jekyll，因此遊戲網站是從Markdown文件生成的。我打算製作遊戲的高級預裝盒和自行打印版本，為此我需要從Markdown文件生成PDF。

目標

我的理想工作流程是在生成網站的同時生成PDF文件，而不是在訪問者請求時生成文件。這排除了我通常用於PDF生成的選項wkhtmltopdf，因為它是從已生成的HTML生成PDF。另一個原因是，我希望PDF卡片版本與HTML頁面看起來不同，而Jekyll缺乏任何類型的“查看模式”功能來實現這一點，而無需使用複雜的CSS規則。

Chip Shop遊戲的卡片Markdown模板文件包含許多用於遊戲機制的Markdown前置信息字段，並非所有字段在每張卡片上都使用。為了方便打印，我需要盡可能多地將卡片放在A4頁面上——在本例中，是一個3×3的網格。最終，頁面需要雙面打印，但我還沒有實現這一點。

Pandoc和LaTeX

任何搜索從Markdown生成PDF解決方案的網絡搜索都會引導您走上Pandoc的道路。 Pandoc是一個開源的瑞士軍刀式標記轉換工具，支持種類繁多且不斷增長的輸入和輸出標記格式。

要使用Pandoc生成PDF，需要LaTeX。 LaTeX起源於科學研究界，是一個文檔聲明和佈局系統。結合Pandoc和LaTeX，我們可以使用變量，從而從一系列Markdown文件生成PDF並支持Markdown前置信息。

儘管Pandoc和LaTeX功能強大，但我找不到任何將多個PDF（卡片）組合到一頁上的方法，尤其是在使用Markdown文件中的變量時。經過大量研究，我選擇了PDFJam，這是一個簡單的命令行工具，用於滿足此需求。

安裝依賴項

Markdown

除了可能需要一個編輯器之外，您不需要額外的Markdown軟件，編輯器有很多，我建議您閱讀一些SitePoint文章來做出選擇。

Jekyll

我將在從我的遊戲中獲取的示例中繼續使用Jekyll來說明構建過程，但如果您不需要網站，它不是PDF生成的必要部分。

Pandoc

在我的Mac上，我使用Homebrew安裝了Pandoc，但所有操作系統都有相應的選項。

LaTeX

關於安裝LaTeX的最佳方法有很多說法，這取決於您的需求或打算如何使用它。其常用工具和庫的完整安裝可能接近2GB，但對於大多數用途而言，最小安裝就足夠了。閱讀項目的下載頁面以找到最適合您的選項。

在本教程中，我們將使用xelatex引擎，因為我使用自定義字體。但是，您可以選擇任何提供您所需特定功能的引擎。

PDFJam

根據您安裝LaTeX的方式，您可能已經安裝了PDFJam。 （在終端中鍵入which pdfjam進行檢查。）如果您沒有安裝，請在此處查找安裝詳細信息。

構建過程

經過一番考慮，我運行在本地運行的bash腳本目前似乎是最佳選擇。有更好的方法，但它有效，我以後可以改進這個過程，將其轉移到持續集成系統或Git Hooks。

在GitHub上查看bash腳本。

現在讓我們逐步介紹這個腳本。

設置

bundle install
bundle update

rm -dfr _site
rm -dfr pod

這些命令確保Jekyll構建網站所需的Ruby依賴項是最新的，並且我們刪除了任何現有的網站和打印文件夾。

構建網站

jekyll build
mkdir -p pod/pdf/cards

接下來，我們構建網站並為卡片的打印版本創建一個文件夾。

從Markdown生成PDF

讓我們創建一個包含每個Markdown文件PDF版本的文件夾：

for filename in _cards/*.md; do
  echo $filename
  pandoc --from=markdown+yaml_metadata_block --template _layouts/cards.latex -o pod/pdf/cards/"$(basename "$filename" .md)".pdf --latex-engine=xelatex $filename
done

該腳本處理_cards目錄中的每個Markdown文件，確保觀察Markdown前置信息字段。使用cards.latex模板（我們將在後面介紹），正確的LaTeX引擎會輸出具有適當名稱的PDF。

LaTeX文件

從Pandoc生成卡片文件的大部分神奇之處都發生在LaTeX模板中。

在GitHub上查看LaTeX模板。

LaTeX對我來說是新的，但它並不太複雜。我將解釋我從默認LaTeX文件（位於Pandoc_install_dir/data/templates/default.latex）中更改的內容以使卡片正常工作。我推薦sharelatex.com用於在編輯LaTeX文件時預覽它們。

bundle install
bundle update

rm -dfr _site
rm -dfr pod

我們需要特定的頁面大小，我們稍後將使用列來顯示卡片的成本和分數。我們正在使用圖形和自定義字體，因此我們需要這些包。

我們試圖創建一個清晰簡潔的簡單佈局。以下是我們如何實現它的：

jekyll build
mkdir -p pod/pdf/cards

我覺得上面很多內容對於任何習慣於代碼或標記的人來說都是相當容易理解的。我們正在創建卡片的元素，對齊它們，設置字體大小並檢查是否有值，然後再輸出它們，這樣卡片就不會最終出現空字段。

我們將圖像調整為特定大小並居中。成本和分數值採用兩列佈局，使用begin{tabular}命令設置，列數使用l的數量設置。

將卡片組合到一頁上

我們使用PDFJam創建一個大型PDF文件，其中包含每個單獨的PDF卡片：

for filename in _cards/*.md; do
  echo $filename
  pandoc --from=markdown+yaml_metadata_block --template _layouts/cards.latex -o pod/pdf/cards/"$(basename "$filename" .md)".pdf --latex-engine=xelatex $filename
done

使用此命令，我們指定以下內容：

• 頁面方向應始終為縱向
• 每個單獨的PDF都應加框
• 網格大小
• 文件名後綴
• 文件名

如果您沒有輸出到其工作目錄，PDFJam可能會給出錯誤，因此我將文件移動到我實際想要的位置（希望將來可以解決）。在這裡，如果我們不需要，我們也可以刪除單個PDF文件。

就這樣——我們有了一個網站和遊戲卡片的可打印PDF。

運行腳本

我使用./build.sh運行構建腳本。由於有很多圖像和PDF處理，因此大約需要五到十分鐘。然後我有一個單獨的腳本將這些文件夾部署到Web服務器。

後續步驟

這個過程花了我一段時間才弄對，但現在已經足夠好，可以在遊戲測試後繼續改進過程和佈局。

我希望您發現我的研究和實驗對您的項目有用。如果您有任何意見或建議，請告訴我。

關於使用Pandoc和LaTeX從Markdown創建PDF的常見問題解答（FAQ）

如何在我的系統上安裝Pandoc和LaTeX？

要安裝Pandoc，您可以從官方網站（https://www.php.cn/link/8f1dd6e7a88b9cf615c146330c591ba9。

我可以自定義使用Pandoc和LaTeX創建的PDF的外觀嗎？

是的，您可以使用LaTeX模板自定義PDF的外觀。 Pandoc使用默認模板生成PDF，但您可以使用--template選項指定您自己的模板。您可以創建自己的模板或使用在線提供的眾多模板之一，例如在Wandmalfarbe Pandoc LaTeX模板GitHub存儲庫中找到的那些模板。

如何使用Pandoc和LaTeX將Markdown文件轉換為PDF？

要將Markdown文件轉換為PDF，您可以在終端或命令提示符中使用以下命令：pandoc yourfile.md -o yourfile.pdf。將yourfile.md替換為您Markdown文件的名稱，將yourfile.pdf替換為您PDF文件的所需名稱。此命令告訴Pandoc使用默認LaTeX模板將Markdown文件轉換為PDF。

（其餘FAQ內容與原文相同，此處省略以避免重複）

以上是用Pandoc和Latex從Markdown創建PDF的詳細內容。更多資訊請關注PHP中文網其他相關文章！