Markdown 基礎語法與論文寫作應用｜VS Code 設定與 Pandoc 參考文獻教學

多數的人聽到Markdown，應該會覺得好像只有工程師才會需要用到？你沒想錯！每個Github Repo都會有的README.md就是Markdown。我第一次知道Markdown也可以寫論文的時候，是從一位博士後研究員那邊聽到的，他驕傲的說他整本博論都是用Markdown寫的，我驚訝到腦袋當機。雖然過了這麼多年，我的論文首選還是以Latex為主（所有的比賽申請函，與政府機關溝通的文件，工作進度紀錄都是Latex），但因為它用任何文字編輯器都可以開，語法也不是很難，對於需要常常快速筆記思緒，又非常糾結排版的我來說，它是一個很棒的工具。我很推薦不管是讀文科還是理科的學生，都來學一下這個厲害的小東東。

我的作業環境

我很推薦VS Code，因為它有一個Plugin可以提供 HTML 預覽，對於我這種視覺型人類來說，超讚！VS Code的連結這邊請（按一下）。安裝之後，順手再裝一個Markdown All in One，然後我們就可以開始寫作囉！

Markdown起手式 - Meta data

一個文件在一開始一定會有的就是作者，日期，文章的標題，這些就可以用YAML型的header來標注起來。你看，多貼心！這種meta-data都有特定格式，這點超、德、國！

還有一個重點就是，用Markdown寫文章的話，YAML裡就少不了一個文獻引用的欄位了，所以以下的這個，歡迎copy & paste & 修改當作萬用格式。

--- 
title: 'Markdown與Pandoc的完美工作流'
author: 'CodeByCradle'
date: '2025 年 11 月 17 日'
abstract: | # 這篇文章目的在做簡單的markdown與pandoc的結合教學。希望這個文章能夠幫助新手，快速學習最基礎的markdown以及如何使用pandoc
keywords: [Markdown, Pandoc, 學術寫作, LaTeX]
bibliography: references.bib
csl: chicago-notes-bibliography-annotated-abstract.csl
link-citations: true
documentclass: ctexart
mainfont: "Songti TC"
sansfont: "PingFang TC"
monofont: "PingFang TC"
lang: 'zh-TW'

---

重要基礎語法

幾個基礎的原則提供給大家

井字號（#）就是各類header

標題是一個#字號，但是這個我們在YAML格式裡面就已經用了title來表示了，所以在寫論文的時候就不需要再寫一次標題。如果是寫程式的工程師，要存檔在GitHub上面的README.md，這個標題還是需要的。
Section header是兩個#字號，適用於緒論，方法，結果等等等。
Subsection header是三個#字號。

以此類推Subsubsection header 是四個井字號，原則上可以無限sub sub sub下去喔！（但說真的，有這麼多subheader的出現，這篇文章會變成什麼樣子啦！！！）

星號（*)就是字體變形

斜體字是一顆星號包圍文字，就像這樣

*這是斜體*

粗體字是兩顆星號包圍文字，就是這樣

**這是粗體**

條列型的話是文字前面一顆星號就好

條列型的內容就像這樣:
* 這是一個條列
* 這又是一個條列

插入圖片

插入圖片也可以簡單做到，但不要忘記先建立一個folder，在folder裡面放圖，然後把path給寫進小括號裡面。不要忘記那個驚嘆號，以前我常常忘了寫，然後compile半天一張圖都沒有。

![圖片說明文字 (Caption)](./images/figure-1.png)

表格製作

我個人覺得要做表格的話，Latex還是強一點，可以做點花俏的欄位合併之類的，但markdown就可以達到基礎的表格了，對於速記速寫還是非常棒的一個特點。
中間那個隔線也非常重要。

如果隔線是 :---: 那就是置中
如果隔線是 :--- 是對其左邊
如果隔線是 ---: 是對其右邊

| 欄位 1 | 欄位 2 | 欄位 3 | 
| :--- | :---: | ---: | 
| 這邊是第一行第一欄 | 這邊是第一行第二欄 | 這邊是第一行第三欄| 
| 這邊是第二行第一欄 | 這邊是第二行第二欄 | 這邊是第二行第三欄|

引用與參考文獻 (Reference Citation)

這一個就是工程師不需要知道，但學生一定要會的技巧了。首先我們要去下載兩個很酷的小玩意叫做pandoc (以下提供brew的installation方法)

brew install pandoc

還有LaTeX (沒錯！我們還是要靠LaTex，畢竟是排版軟體嘛....)。因為如果是蘋果用戶，請安裝MacTex

接下來，我們要先弄個文獻檔案，格式就大致長下面這樣，每一個@的後面跟的都是一篇文章的資料，它可以是學術期刊，一本書，也可以是網頁等等等，但因為不同的資訊有不一樣的內容，所以詳細的bib格式還是要去找網站來看一下，我最懶的時候每一個reference都是@misc（然後被老闆電到整個人草灰搭 ....）

@article{引用ID,
title={文章標題},
author={作者},
year={2025}
}

@article{smith2020, 
  title={The science of Markdown},
  author={Smith, John},
  journal={Journal of Academic Writing},
  volume={10},
  pages={1--20},
  year={2020}
}

@book{doe2019,
  title={Writing with Pandoc},
  author={Doe, Jane},
  publisher={Tech Press},
  year={2019}
}

如果是用Endnote的各位.....去問你老師怎麼搞出一個bib檔，本人沒用過Endnote。

寫文章的時候我們就可以用方形括號加上引用ID，就像這樣


Smith (2020)的研究[@smith2020]，我沒有看過。

Doe (2019)的研究[@doe2019]，我也沒有看過。

但既然這兩個研究好像是Markdown教學的必備文獻，我就把這兩個研究放在這邊了。

我們已經有一個reference.bib跟一個cls了，接下來就是 compile PDF!

Pandoc 會自動在這邊（或文件的最末端）生成「參考文獻」列表。

記得再去下載一個cls檔案作為文獻引用的格式，這邊不負責任的隨便用個芝加哥格式，但寫文章時，千萬不要隨便挑選，請使用期刊規定的格式。

一切都齊備之後，我們就可以來compile了。如果是Mac或是Unix系統的使用者請打開Terminal。Windows的使用者，要打開最古早的那個命令提示字元（天兒喔！我還記得它中文叫做命令提示字元！），我沒有試過用Powershell來呼叫Pandoc，歡迎有這樣用過的朋友們來分享一下，Powershell能不能用。

下面這個，請直接copy & paste做點修改，這串我永遠背不起來。

pandoc main.md -o paper.pdf --pdf-engine=xelatex --citeproc

希望這樣有幫助到各位一點點！