核心要點

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

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

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

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

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

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

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

目標(biāo)

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

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

Pandoc和LaTeX

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

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

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

安裝依賴項

Markdown

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

Jekyll

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

Pandoc

在我的Mac上，我使用Homebrew安裝了Pandoc，但所有操作系統(tǒng)都有相應(yīng)的選項。

LaTeX

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

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

PDFJam

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

構(gòu)建過程

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

在GitHub上查看bash腳本。

現(xiàn)在讓我們逐步介紹這個腳本。

設(shè)置

bundle install
bundle update

rm -dfr _site
rm -dfr pod

這些命令確保Jekyll構(gòu)建網(wǎng)站所需的Ruby依賴項是最新的，並且我們刪除了任何現(xiàn)有的網(wǎng)站和打印文件夾。

構(gòu)建網(wǎng)站

jekyll build
mkdir -p pod/pdf/cards

接下來，我們構(gòu)建網(wǎng)站並為卡片的打印版本創(chuàng)建一個文件夾。

從Markdown生成PDF

讓我們創(chuàng)建一個包含每個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引擎會輸出具有適當(dāng)名稱的PDF。

LaTeX文件

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

在GitHub上查看LaTeX模板。

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

bundle install
bundle update

rm -dfr _site
rm -dfr pod

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

我們試圖創(chuàng)建一個清晰簡潔的簡單佈局。以下是我們?nèi)绾螌崿F(xiàn)它的：

jekyll build
mkdir -p pod/pdf/cards

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

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

將卡片組合到一頁上

我們使用PDFJam創(chuàng)建一個大型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

使用此命令，我們指定以下內(nèi)容：

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

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

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

運行腳本

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

後續(xù)步驟

這個過程花了我一段時間才弄對，但現(xiàn)在已經(jīng)足夠好，可以在遊戲測試後繼續(xù)改進過程和佈局。

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

關(guān)於使用Pandoc和LaTeX從Markdown創(chuàng)建PDF的常見問題解答（FAQ）

如何在我的系統(tǒng)上安裝Pandoc和LaTeX？

要安裝Pandoc，您可以從官方網(wǎng)站（http://miracleart.cn/link/8f1dd6e7a88b9cf615c146330c591ba9。

我可以自定義使用Pandoc和LaTeX創(chuàng)建的PDF的外觀嗎？

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

如何使用Pandoc和LaTeX將Markdown文件轉(zhuǎn)換為PDF？

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

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

以上是用Pandoc和Latex從Markdown創(chuàng)建PDF的詳細內(nèi)容。更多資訊請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！