核心要點(diǎn)

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

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

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

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

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

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

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

目標(biāo)

我的理想工作流程是在生成網(wǎng)站的同時(shí)生成PDF文件，而不是在訪問(wèn)者請(qǐng)求時(shí)生成文件。這排除了我通常用於PDF生成的選項(xiàng)wkhtmltopdf，因?yàn)樗菑囊焉傻腍TML生成PDF。另一個(gè)原因是，我希望PDF卡片版本與HTML頁(yè)面看起來(lái)不同，而Jekyll缺乏任何類型的“查看模式”功能來(lái)實(shí)現(xiàn)這一點(diǎn)，而無(wú)需使用複雜的CSS規(guī)則。

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

Pandoc和LaTeX

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

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

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

安裝依賴項(xiàng)

Markdown

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

Jekyll

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

Pandoc

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

LaTeX

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

在本教程中，我們將使用xelatex引擎，因?yàn)槲沂褂米远x字體。但是，您可以選擇任何提供您所需特定功能的引擎。

PDFJam

根據(jù)您安裝LaTeX的方式，您可能已經(jīng)安裝了PDFJam。 （在終端中鍵入which pdfjam進(jìn)行檢查。）如果您沒(méi)有安裝，請(qǐng)?jiān)诖颂幉檎野惭b詳細(xì)信息。

構(gòu)建過(guò)程

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

在GitHub上查看bash腳本。

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

設(shè)置

bundle install
bundle update

rm -dfr _site
rm -dfr pod

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

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

jekyll build
mkdir -p pod/pdf/cards

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

從Markdown生成PDF

讓我們創(chuàng)建一個(gè)包含每個(gè)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目錄中的每個(gè)Markdown文件，確保觀察Markdown前置信息字段。使用cards.latex模板（我們將在後面介紹），正確的LaTeX引擎會(huì)輸出具有適當(dāng)名稱的PDF。

LaTeX文件

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

在GitHub上查看LaTeX模板。

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

bundle install
bundle update

rm -dfr _site
rm -dfr pod

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

我們?cè)噲D創(chuàng)建一個(gè)清晰簡(jiǎn)潔的簡(jiǎn)單佈局。以下是我們?nèi)绾螌?shí)現(xiàn)它的：

jekyll build
mkdir -p pod/pdf/cards

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

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

將卡片組合到一頁(yè)上

我們使用PDFJam創(chuàng)建一個(gè)大型PDF文件，其中包含每個(gè)單獨(dú)的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è)面方向應(yīng)始終為縱向
• 每個(gè)單獨(dú)的PDF都應(yīng)加框
• 網(wǎng)格大小
• 文件名後綴
• 文件名

如果您沒(méi)有輸出到其工作目錄，PDFJam可能會(huì)給出錯(cuò)誤，因此我將文件移動(dòng)到我實(shí)際想要的位置（希望將來(lái)可以解決）。在這裡，如果我們不需要，我們也可以刪除單個(gè)PDF文件。

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

運(yùn)行腳本

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

後續(xù)步驟

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

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

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

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

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

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

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

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

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

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

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