利用pandoc將markdown轉換為word文檔

目錄

• 基本使用
• 修改word文檔格式
• 合並多個markdown文件，自動生成目錄
• markdown預處理
• 操作指南：匯總軟工實踐課程博客
• 總結

pandoc可以完成多種文件類型的相互轉換，支持的文件格式參見官方網站：https://pandoc.org/index.html。本博客參考了官方文檔以及社區討論，將介紹如何利用pandoc將markdown轉換為word文檔。

---

基本使用

1. 在Installing頁面選擇合適的版本下載

   

2. 命令行運行基本參數

   • 使用參數-f FORMAT和-t FORMAT指定源和目標文件格式；pandoc支持識別文檔后綴，一般可以省略
   • 使用參數-o FILE指定輸出文件

3. 一個例子

   省略文件格式，使用命令pandoc 課程回顧與總結.md -o 課程回顧與總結.docx，得到的結果如下：

   課程回顧與總結.md	課程回顧與總結.docx

---

修改word文檔格式

使用參數--reference-doc=FILE可以指定docx輸出文件的格式參考對象，從而修改word文檔的格式。

1. 獲取模板

   首先使用命令pandoc -o custom-reference.docx --print-default-data-file reference.docx拷貝一份默認的參考文件模板，取名為custom-reference.docx

2. 修改模板樣式

   用word打開custom-reference.docx，修改各部分對應樣式。例如，將光標移動到Heading 2，找到對應的樣式，右鍵進行修改：

   

   下圖修改了Heading 1和Heading 2，將字體修改為黑體，顏色修改為黑色：

   custom-reference.docx修改前	custom-reference.docx修改后

   如果要修改輸出文件中的表格樣式，直接給模板中的表格更換樣式，不能達成效果。根據Github上的討論得知，必須修改名為Table的表格樣式，才能控制輸出文件的表格樣式。
   

3. 再次轉換文件

   使用命令pandoc 課程回顧與總結.md -o 課程回顧與總結.docx --reference-doc=custom-reference.docx，此次運行結果和之前對比如下，注意到一級標題和二級標題變成黑色：

   默認格式	修改格式后

---

合並多個markdown文件，自動生成目錄

pandoc可以接受多個文件為輸入，例如pandoc file1.md file2.md file3.md -o result.docx；另外有一些參數可以用於自動生成目錄。

1. 生成目錄

   • 使用參數--toc自動生成目錄

     同時可以修改格式參考文件中，TOC標題/TOCHeader的樣式，選中段前分頁，這樣之后手動插入文檔封面會比較方便。

   • 使用參數--toc-depth=NUMBER指定目錄包含的標題深度

     如果每一篇markdown的文章標題都是一級標題，使用--toc-depth=1可以生成最簡單的目錄。

   • 使用參數--reference-doc=FILE指定格式參考文件，並給格式參考文件添加頁碼

     如此生成的文件也會有頁碼。

2. 文件分頁

   pandoc讀入了多個文件，輸出時各個文件的內容是連續的；希望每個文件能從新的一頁開始，檢索互聯網得到兩種解決方式：

   • 格式選擇段前分頁

     一級標題往往是文章標題。如果修改一級標題的格式，選中段前分頁，每一個markdown文件的一級標題就會出現在新的一頁。

     

     參考鏈接：How to add a page break in word document generated by RStudio & markdown

   • pandoc使用filter

     Pandoc provides an interface for users to write programs (known as filters) which act on pandoc’s AST.

     什么是filter，參考官網：Pandoc filters

     如何使用filter達到分頁目的，參考這個回答：Pandoc markdown page break

---

markdown預處理

提前處理markdown源文件，或者根據結果修改markdown文件，以得到排版較好的word文件。

1. 合理使用標題層次

   合並多篇markdown時，注意統一標題層次。

2. 合理使用markdown語法

   例如，避免僅僅為了排版美觀而使用引用語法；markdown引用在word文件中顯示效果不同，錯誤使用可能會產生奇怪的效果。

3. 注意縮進和空行

   使用縮進和空行以體現段落關系。觀察下面兩個結果：

   markdwon	word

4. 避免手動換行排版

   markdown中不要為了讓每行文字數量相同而手動使用回車換行。

5. 替換html標簽（暫時沒有找到支持的方式）

   如果使用了html表格/圖片等，需要替換成相應的markdown語法。

---

操作指南：匯總軟工實踐課程博客

1. 下載群文件：文檔封面和提前處理好的格式參考文件custom-reference.docx

   • 后者參考了福大畢業論文撰寫規范，提前調整了部分格式
   • 后者僅修改了前四級標題格式；如果有需求，需要自行修改其他部分的格式

2. 整理好歷次作業的markdown文件

   • 參考markdown預處理中的內容修改源文件
   • 用作業的名字給每篇博客添加一級標題，用於生成目錄，同時產生分頁效果

3. 在命令行運行pandoc hw1.md hw2.md hw3.md -o result.docx --reference-doc=custom-reference.docx --toc --toc-depth=1

   • 命令中markdown文件的名字、數量和順序，以及輸出文件的名字，根據自己的情況填充

4. 核查所有內容是否正確顯示；如果不是，調整markdown源文件，再次生成結果

5. 根據實際情況，調整有問題的文字格式/圖片/表格/代碼段/列表縮進

6. 修改目錄標題Table of Contents為目錄

7. 手動插入封面並填寫相關信息

8. 有必要時，調整頁碼（例如去除封面和目錄部分的頁碼）

---

總結

個人感覺pandoc對於docx的格式控制是有限的。如果對word操作很熟練，使用pandoc的基本轉換功能就可以，后續的格式/目錄/頁碼都能夠在word文檔中完成。如果不熟悉word，或者希望pandoc提供一些便利，這篇博客的其他部分可以提供一些幫助。