使用 Pandoc 和 Docker 創建發布鏈

已發表: 2022-03-11

今天，我們將仔細研究專業人士如何獲得 Pandoc 的幫助，以創建一個強大且易於實施的發布鏈。 Pandoc 是一個非常簡單但功能強大的工具，它允許用戶根據自己的要求將文檔轉換為各種格式。

它可以極大地簡化文檔和發布，甚至開闢一些新的自動化可能性。 最重要的是，Pandoc 依賴於 Git 友好的 Markdown，這意味著您還可以為您的文檔實施版本控制系統，而無需任何額外的麻煩。

說到麻煩，我們將依靠 Docker 映像通過簡單的拉取來安裝 Pandoc 和 LaTeX。 安裝軟件可能很耗時，並且在開始新項目時從頭開始設置工作軟件環境幾乎沒有效率。 Docker 允許用戶在幾分鐘內完成所有設置，無論平台如何，都有助於緩解這些問題。

此外，雇主要求您提供自己的計算機硬件的情況並不少見。 這通常被稱為自帶設備 (BYOD)，我們不要忘記 COVID-19 大流行使在家工作變得更加普遍。 如果沒有像 Docker 這樣的解決方案，就很難支持在 Windows、macOS 和 Linux 等不同硬件和操作系統上運行的應用程序。

在繼續討論 Pandoc 之前，讓我們先仔細看看 Docker 容器和映像。

Docker 救援

使用 Docker 容器可以消除在新機器上安裝多個軟件應用程序的需要。 Docker Hub 上為大量應用程序提供了預構建的 Docker 映像。 AWS、Azure 和 Google 等領先的雲提供商都提供容器註冊表。 還有許多其他第三方註冊表，包括 GitLab 和 Red Hat OpenShift。

大多數（如果不是全部）應用程序都可以使用圖像。 這意味著不需要安裝大多數應用程序及其依賴項。 該應用程序可以簡單地在 Docker 容器中運行。 這方便地消除了與團隊成員在不同硬件和不同操作系統上運行應用程序相關的問題。 同一個鏡像可用於在任何可以運行容器的系統上運行容器，而 Docker 專家可以使這個過程變得非常快速和高效。

Pandoc 用例：文檔

可能需要幾種不同格式的文檔。 相同的文檔可能需要以不同的格式提供，例如用於演示的 HTML 和用於講義的 PDF。 在文件格式之間進行轉換可能很乏味並且需要大量時間。 一個好的解決方案是擁有一個具有單一事實來源的發布鏈。 所有文件都應使用相同的語言編寫。 它應該是一種基於文本的語言，因為它更容易在 Git 存儲庫中進行版本控制和存儲。

Markdown 是創建單一事實來源的不錯選擇。 可以將 Markdown 文檔轉換為各種其他格式的軟件很容易獲得併且往往是可靠的。

Markdown 可以很容易地轉換成一系列不同的格式用於各種用途
Markdown 可以很容易地轉換為一系列不同的格式以用於各種用途。

潘多克

Pandoc 是一個可以將文檔轉換為不同格式的軟件包。 特別是它可以將 Markdown 轉換為 HTML、PDF 和其他廣泛使用的格式。 可以使用 Markdown 源中的模板和元數據自定義轉換過程。

Pandoc 需要安裝 LaTeX 才能創建 PDF 文件。 安裝 Pandoc 和 LaTeX 非常耗時。 幸運的是，有一個名為pandoc/latex的 Docker 映像，它消除了安裝 Docker 以外的任何東西的需要。

碼頭工人命令

需要找到或創建包含必要軟件的合適 Docker 映像。 建議將映像拉到本地註冊表，因為下載可能需要一些時間。

 docker pull pandoc/latex

要在 Docker 容器中運行命令，需要一個包裝器來運行 Docker 容器並在容器中執行命令。 一個很好的解決方案是在 macOS 或 UNIX/Linux 系統上編寫一個 shell 函數。 該函數可以放在任何登錄腳本中，也可以放在單獨的文件中，例如$HOME/.functions 。 也可以編寫具有相同功能的腳本或別名。

 function pandoc { echo pandoc $@ docker run -it --rm -v $PWD:/work -w /work pandoc/latex pandoc "$@" }

此函數執行以下操作：

  • 它將命令打印到屏幕上。
  • 它從pandoc/latex映像運行 Docker 容器。
  • -it選項創建一個交互式終端會話並使命令的輸出可見。
  • --rm選項在命令終止後刪除容器。
  • -v $PWD:/work選項將主機上的當前目錄掛載到容器中的目錄/work上。
  • -w /work使容器中的/work目錄成為工作目錄。
  • 最後的pandoc "$@"在容器中運行pandoc命令，傳遞所有傳遞給函數的命令行選項。

shell 或腳本需要將函數加載到內存中。

 . $HOME/.functions

該函數現在本身就是一個命令，其行為方式與本地安裝pandoc二進製文件的方式相同。 此方法可用於 Docker 映像中可用的任何命令。

降價到 HTML

要將 Markdown 轉換為 HTML，最好在 Markdown 中使用模板和元數據。

降價到 HTML

降價元數據

Markdown 源可以有一個可以包含任意元數據的標題部分。 元數據採用鍵值對的形式。 這些值可以在 HTML 模板中替換。

 --- title: Document title links: prev: index next: page002 ...

標題以僅包含三個破折號的行開頭--- 。 它以僅包含三個點...的行結束。 鍵是單個單詞，後跟一個冒號及其值。 鍵可以嵌套。 該示例顯示了名為title, links.prev和links.next的鍵的定義。

這種方法對每個頁面使用單獨的文件。 在示例中，上一頁是index.md ，當前頁是page001.md ，下一頁是page002.md 。 在實踐中，將使用更有意義的文件名，以便更容易重新排序和插入頁面。

HTML 模板

HTML 模板只是一個 HTML 文件。 可以在美元符號之間添加元數據替換和簡單的控制結構。 這是 Pandoc 的 HTML 模板的簡單示例：

 <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>$title$</title> <link href="../css/style.css" type="text/css" rel="stylesheet" /> </head> <header> <h1>$title$</h1> </header> <body> $body$ </body> <footer> $if(links.prev)$ <a href="$links.prev$.html" class="previous">&laquo; Previous</a> $endif$ $if(links.next)$ <a href="$links.next$.html" class="next">Next &raquo;</a> $endif$ </footer> </html>

該示例顯示了一個模板。 $body$被轉換為 HTML 的 Markdown 文本替換。 只有在 Markdown 標頭中定義了元數據時，條件語句才會生成 HTML 鏈接。

從 Markdown 生成 HTML

Pandoc 只需要被告知輸入和輸出文件的名稱以及任何模板文件。 默認輸入文件格式是Markdown 。 它可以從指定的輸出文件擴展名推斷輸出文件格式。

生成輸出的命令可以是腳本或 makefile。

 dir=Project for input_file in ${dir}/*.md do output_file=HTML/${input_file%.md}.html if [[ ${input_file} -nt ${output_file} ]] then pandoc --data-dir . --template presentations.html -t html \ -o ${output_file} ${input_file} fi done

對於Project目錄中的每個.md文件，如果輸出文件早於輸入文件或不存在，它將在HTML/Project目錄中創建相應的.html文件。

從 Markdown 生成 Beamer PDF

Beamer 是一個用於製作演示文稿的 LaTeX 包。 輸出為 PDF 幻燈片。

從 Markdown 生成 Beamer PDF

相同的 Markdown 源文件可用於生成 beamer PDF。

 pandoc -t beamer -o PDF/Project.pdf -V theme:Boadilla -V colortheme:whale Project/index.md Project/page000.md

命令詳情如下：

  • -t beamer選項表示使用 LaTeX 和 beamer 生成 PDF。
  • -o選項指定輸出文件。
  • -V選項選擇投影儀主題和顏色主題。
  • 該命令以 Markdown 文件列表結尾，這些文件將按給定順序連接。

所有處理都在 Docker 容器內執行。

降價到 PDF

將 Markdown 文檔轉換為 PDF 文檔也很簡單。 PDF 總是通過首先將 Markdown 轉換為 LaTeX 來生成的。 可以將元數據添加到 Markdown 標頭以自定義輸出，例如設置紙張大小和邊距大小。

 --- title: Title of document papersize: a4 geometry: - margin=20mm ...

從 Markdown 生成 PDF

將 Markdown 轉換為 PDF 的命令很簡單：

 pandoc -s Project/outline.md -o PDF/ProjectOutline.pdf

-s 選項創建一個獨立的文檔。

結論

不再需要花費很多天來安裝軟件。 只需在 Docker 容器中運行命令即可消除安裝需求。 許多應用程序在 Docker Hub 上都有合適的 Docker 鏡像。 如果軟件需要更新，只需拉取最新的 Docker 鏡像。

設置一台新計算機只需安裝 Docker、拉取必要的映像並創建一些腳本。

不再需要創建不同格式的文檔。 Markdown 等單一格式可用於所有文檔。 然後像 Pandoc 這樣的工具可以從 Markdown 生成大量不同格式的文檔。

由於 Markdown 是一個文本文件，當簽入 Git 存儲庫時，可以使用完整的版本歷史記錄。 Git 存儲庫還自動呈現 Markdown 並允許人們對更改發表評論，而無需在文檔文件本身中使用凌亂的更改歷史記錄。