Pandoc Template for NTU Thesis

• HTML
• Overleaf

此專案是 Pandoc 的臺大碩博士論文模板，讓使用者能透過 (Pandoc) Markdown 語法撰寫論文 (無須安裝與了解 LaTeX!!)。此專案的前身是 ntuthesis2 (Python Script) 以及 ntuthesis (R 套件)。這個版本大幅精簡了先前的相依需求。

輸出論文

GitHub

如果你有 GitHub 帳號，可以透過 GitHub Action 直接輸出論文 (Overleaf 專案連結與 HTML)，無需在電腦上安裝任何東西。只要 fork 此 Repo，每次 push commit 至 GitHub 後，即會以靜態網頁以及 Overleaf 專案的形式輸出論文。

• 靜態網頁的網址：https://{user}.github.io/{repo}，例如 https://liao961120.github.io/thesis。
• Overleaf 專案的網址為： https://www.overleaf.com/docs?engine=xelatex&main_document=main.tex&snip_uri=https://{user}.github.io/{repo}/overleaf.zip，例如 https://www.overleaf.com/docs?engine=xelatex&main_document=main.tex&snip_uri=https://liao961120.github.io/thesis/overleaf.zip。點擊進入這網址後，Overleaf 就會自動匯入專案並輸出 PDF。

個人電腦

Linux & Mac

如果想在本機預覽 HTML 輸出結果，需安裝 Pandoc 2.14 (或更新) 以及 pandoc-crossref。安裝之後，至 Terminal 執行下方指令:

bash build-html.sh  # 輸出 docs/index.html
bash build-tex.sh   # 輸出 docs/overleaf.zip，可上傳至 Overleaf 或是自己輸出成 PDF

Windows

Windows 使用者將此 repo clone 至本地端後，下載 win-bash.zip 。解壓縮後，將 win-bash/ 置於 repo 的根目錄，打開 cmd 或 powershell 執行:

.\win-bash\PortableGit\bin\bash.exe win-build-html.sh
.\win-bash\PortableGit\bin\bash.exe win-build-tex.sh

透過 VSCode 預覽 Pandoc

VSCode 的擴充套件 Markdown Preview Enhanced 支援使用 Pandoc 作為 Markdown 的 Parser，對於撰寫論文時很有幫助 (即時預覽)。另一個套件 Pandoc Citer 則可協助於 markdown 裡插入引用文獻。建議可以將下方的設定加入 VSCode 的 settings.json:

{
  ...,
  "markdown-preview-enhanced.usePandocParser": true,
      "markdown-preview-enhanced.pandocArguments": [
          "--filter=pandoc-crossref",
          "--lua-filter=deps/pandoc-ling.lua",
          "--citeproc",
          "--mathjax",
          "--number-sections",
          "--include-in-header=deps/style.html",
          "--bibliography=references.bib",
      ],
  "PandocCiter.DefaultBib": "references.bib",
  "PandocCiter.UseDefaultBib": true
}

論文語言設定

論文可以使用中文或是英文撰寫。相關的設定在 setup.md 開頭的 yaml。若 acknowledgement-in-en 為 true, 則論文中的標題會是 "Acknowledgement"；反之，則為「致謝辭」。

---
language     : "chinese"  # chinese | english
acknowledgement-in-en: false  # true for english
---

此外，由於 Pandoc 處理 in-text citation 的預設行為可能不適合中文論文 (多出不必要的空白)，可至 build-html.sh 以及 build-tex.sh 中，將下方這行移除：

# 其它內容...
    --lua-filter deps/lua/rmCiteSpace.lua \
# 其它內容...

使用

由於 LaTeX (TeX Live 或 MikTeX) 的安裝十分令人頭痛，而且即使安裝完成，後續生成 PDF 的過程仍會常常出錯。為了儘量避開這些問題，此專案在設計上結合 Overleaf，讓使用者能將輸出的 .tex 檔透過 (免費) 網路服務輸出成 PDF 檔。當然，若使用者個人電腦上已有 LaTeX，也可直接在電腦上輸出 PDF。此外，這裡亦提供一個簡約的 HTML 輸出格式，目的是方便在撰寫時預覽論文 (因為 LaTeX 的輸出相當耗時)。

論文撰寫

下方為 Repo 的結構，基本上使用者僅需要更動兩個地方---setup.md 以及 chapters/ 裡的檔案。其它部份若不清楚是什麼可以不用理會，也不要去刪除它們。

/
├── setup.md               # 論文參數設定 (標題、作者、指導教授、摘要、謝辭...)
├── build-html.sh          # 輸出 HTML
├── build-tex.sh           # 輸出 overleaf.zip (可上傳至 Overleaf compile)
├── docs/                  # 論文輸出
├── chapters/              # 論文內容
│   ├── 01-intro.md           # 第一章 (命名規則：{##}-{title}.md)
│   ├── 02-chapter2.md        # 第二章 (命名規則：{##}-{title}.md)
│   ├── appendix-A.md         # 附錄 A (命名規則：appendix-{編碼}.md)
│   ├── appendix-B.md         # 附錄 B (命名規則：appendix-{編碼}.md)
│   ├── denotations.md        # 符號列表 (若無需用到，請將檔案裡的內容刪除，但勿刪除此檔案)
│   ├── references.yaml       # 引用書目 (CSL YAML)
│   └── figures/              # 圖片存放處 (勿刪除此資料夾)
└── deps/                  # 論文模板、程式輸出相依檔案
    ├── ...
    └── citation-style.csl # 引用格式 (至 zotero.org/styles 下載)

更詳細的內容，請見說明文件。

Issues

若有使用上的問題，可在 GitHub 回報。若沒有 GitHub 帳號，可透過 Email 聯絡 Yongfu Liao。

特別感謝

此論文的 LaTeX 模板是根據 Hsins/NTU-Thesis-LaTeX-Template 修改而成。