一些 Pandoc 常用的 Markdown 語法及注意事項

一些 Pandoc 常用的 Markdown 語法及注意事項

參考資料:https://pandoc.org/README.pdf

基礎須知:Markdown 相對於其他文書格式,並非「易撰寫」,而是「易閱讀」,因此在語法上有很多種表達方式,擇一即可。

在需要特殊排版要求時才會加入 html 語法,而 html 語法中的任何 Markdown 記號都會視為通常字元。

這裡介紹的為 Pandoc 支援的語法,Pelican 轉換網誌時可能無法支援。

為編輯方便,這篇文章使用 Leo Editor 的 @others@clean 語法編輯文件。

目錄

  1. 書目與換頁

  2. 換行記號

  3. 標題

  4. 分隔線

  5. 粗體與斜體

  6. 清單

  7. 連結

  8. 表格

  9. 數學符號

  10. 程式碼

  11. 參考文獻

  12. 注意事項

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 的數學公式,可以藉由網頁服務轉換。

http://www.hostmath.com/

使用時兩端包上錢幣符號,如下:

$$\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