一些 Pandoc 常用的 Markdown 語法及注意事項
一些 Pandoc 常用的 Markdown 語法及注意事項
參考資料：https://pandoc.org/README.pdf
基礎須知：Markdown 相對於其他文書格式，並非「易撰寫」，而是「易閱讀」，因此在語法上有很多種表達方式，擇一即可。
在需要特殊排版要求時才會加入 html 語法，而 html 語法中的任何 Markdown 記號都會視為通常字元。
這裡介紹的為 Pandoc 支援的語法，Pelican 轉換網誌時可能無法支援。
為編輯方便，這篇文章使用 Leo Editor 的 @others 和 @clean 語法編輯文件。
目錄
Pandoc 書目與換頁
書目
使用百分比符號隔著 1 到 4 格空白，插入置中封面文字。
% 封面標題 % 作者 % 28, January, 2017 --- 內文不能再使用
換頁
換頁記號使用後不用再換行。
\newpage
換行記號
使用空行的方式來作換行，如下：
1 2 3 | 第一段文字
第二段文字
|
「看起來像」空行也會被視作空行，如該行只有空白或 tab 字元。
若是沒有換行，兩段緊貼的文字仍會視為同一段。
若要插入一段空行，可以用反斜線 \ 符號加上一個以上的空白字元。
標題
每個標題中都內建錨點，相當於 html 的 h1, h2, h3。
分成 Setext 和 Atx 兩種形式，而這兩種形式是可以混用的。
在 Pandoc 中，每個標題都會轉為 PDF 的目錄書籤。
Setext 形式
使用 3 個或以上的「等於」與「減號」代表 h1 和 h2。
This is an H1 === This is an H2 -------------
Atx 形式
井字號的數量決定層級。
# This is an H1 ## This is an H2 ###### This is an H6
分隔線
使用 3 個或以上的「星號」、「減號」、「下底線」來畫出水平分隔線。
水平線的符號必須被空白圍繞，若是緊貼其他文字則會失效。
--- * * * * _____
粗體與斜體
在內文中標記粗體與斜體，兩者可以混用，但是開頭與結尾必須一致。
論文中比較少用兩者，可以在寫網誌時畫重點。
使用「星號」或「下底線」代表斜體。
*斜體文字* _斜體文字_
使用雙「星號」或「下底線」代表粗體。
**粗體文字** __粗體文字__
清單
清單分為無序和有序，都可以使用降階不間段放入內容。
使用「星號」、「減號」、「加號」隔著 1 到 4 格空白來代表無序清單。
* 其中一項
+ 還有一項
+ 還有一項
- 還有一項
* 其中一項
* 其中一項
使用「普通數字」與「英文句號」隔著 1 到 4 格空白放入內容，產生有序清單。可以完全不照順序排版，在最終會自動轉換成順序排列。
1. 永遠的第一項 1. 永遠的第二項 6. 永遠的第三項
連結與圖片
基本的連結樣式：
有一個[連結文字](http://www.google.com)在這裡。
轉移的連結樣式。優點是可以統一放在同一處，並且能重複引用。
要注意冒號後必須有 1 到 4 個空白。
有一個[連結文字][]在這裡。 [連結文字]: http://www.google.com
圖片使用方式跟連結一樣，只須在前端加上驚嘆號。
圖片從自身檔案開始尋找，或是使用網路連結（轉檔時連網即可）。
![圖片名稱][] [圖片名稱]: image/a.jpg
Pandoc 會處理單行的圖片（同行不可有字元），為其置中、編入圖片編號（以章節出現排序），並且在下方置入圖片標籤。
安裝擴充套件 pandoc-fignos 後，使用下面的方式引用：
![圖片名稱][]
請參考圖 {@fig:圖片代稱} 中的內容。
[圖片名稱]: image/a.jpg {#fig:圖片代稱}
表格
Markdown 的表格分為 4 種樣式，並有不同表達法。
正式表格多用管表格表示：
Table: 表格名稱 {#tbl:表格代號}
| Tables | Are | Cool |
|----------|:-------------:|------:|
| col 1 is | left-aligned | $1600 |
| col 2 is | centered | $12 |
| col 3 is | right-aligned | $1 |
參照表 {@tbl:表格代號}
使用網頁服務生成：http://www.tablesgenerator.com/markdown_tables
數學符號
Pandoc 支援插入 Latex 的數學公式，可以藉由網頁服務轉換。
使用時兩端包上錢幣符號，如下：
$$\frac{-b\pm\sqrt{b^2-4ac}}{2a}$$
會生成：
$$\frac{-b\pm\sqrt{b^2-4ac}}{2a}$$
程式碼
Markdown 用簡單的縮排插入程式碼，如：
這是一段 Python 程式：
if __name__='__main__':
print("Hello world!")
印出 Hello world! 字樣。
或是使用重音符（Grave accent）包起單一程式碼：
一段程式：
`print("Hello world!")`
若一大串程式碼，可以用三個以上的重音符包起，也能用語言名稱加註：
Bash 指令： ```bash sudo apt install python3-pip sudo pip3 install markdown ```
參考文獻
將參考資料的資訊放入 bibtex 檔案中，並給予一個識別名稱（如 myart），結構如下：
@article{myart,
author = {作者名字},
title = {標題},
journal = {刊物名稱},
year = 1993,
number = 2,
pages = {201-213},
month = 7,
note = {選擇性註解},
volume = 4
}
接著可以在內文中使用：
參考於書籍[@myart]。
Pabdoc 會自動編碼，套用不同的 csl 檔案可以改變條列外觀。
注意事項
不像其他語言，在 Leo Editor 中使用 @others 與 @clean 編輯 Markdown 論文或技術手冊時，子節點必須多留一個換行。
否則 Leo Editor 在儲存時會把下一個子節點的第一行對齊到前個節點的最後一行，導致沒有換行標記，會誤認這兩行的內容為同一行而沒做換行處理。
更多內容請參見：http://markdown.tw/
Comments
comments powered by Disqus