Markdown / Markdown extra - 一個讓我眼睛為之一亮的新文件語言
前言
在工作中總難免要寫自行記錄的文件, Blog 雖然是很好的工具, 但是作為內部知識分享的文件有點不適合. 目前內部文件都是採用 mediawiki, 可是大部分的 Blog 平台都沒有支援 wiki 語法, 這讓我很頭痛. 因為我每次整理文件還要再重新整理格式, 如果文件撰寫整理都這麼麻煩, 就會降低寫文件的意願. 二來我為了要確保在 Blog 系統上看到的東西格式是我想要的輸出, 通常我都會選擇用 html 的方式然後再加入 JavaScript 外掛讓程式碼好讀並保持格式不會跑掉. 但是儲存後的 html 格式並不會照我原來編排方式儲存. 所以對於我這個老派的程式設計師來說的確會增加我維護的困擾. wiki 語法也開始造成了我文件維護上的困擾, 因為我用的 Project 管理系統 - Redmine 的 wiki 語法跟 mediawiki 是不完全相容的, 所以這讓我頭痛了一陣子. 所以我只好再找找有甚麼解決方案, 然後感謝 google 大神在每次我給了方向正確的關鍵字之後, 總是會給我滿意的答案, 所以我找到了 markdown 這個文件格式.
我也才剛研究這個格式, 但是我馬上就發現了他很多的好處. 我一直不習慣用 html 去編輯文件, 因為它不是一個友善閱讀的格式. 這也是我喜歡 wiki 的原因, 又快又好讀. 但是各家 wiki 語法的混亂讓我有點失望. Markdown 在這方面倒是像極了 wiki. 而且他原本的設計是讓人就算是讀它的原始文件也是很好懂, 至於在這方面 wiki 就不一定佔優勢了. 如果有經歷早期要寫 README 的人來說, markdown 的語法一定會讓他有似曾相似的感覺.
編輯工具
Markdown 有很多種編輯工具, google 一下就有, 但是我不想在本機端裝編輯器又想要把文件同步到雲端 (dropbox/google drive), StackEdit 就是個很好的選擇. StackEdit 的歡迎文件就是個很好的參考文件, 所有支援的語法都在文件裡. 不想看英文的可以看下面的簡易說明.
Markdown 的段落
跟 wiki 不同的是, markdown 語法只要是換行就是換段落了. wiki 則是要空一個空行才算是另一個段落.
Markdown / Mardown Extra 語法
目前我比較常用的就幾種:
- 標題
- 粗體斜體
- 分隔線
- 引述
- 清單
- 連結
- 表格
- 程式碼
- 目錄
有些在 markdown 語法有支援, 有些則是屬於 markdown extra / markdown extra 的語法了.
標題
H1 標題可以是這樣
標題
====
也可以是
# 標題
H2 標題可以是這樣
標題
----
也可以是這樣
## 標題
至於 H3 以下的語法就只能用 # 代替了, 基本上就是幾個 # 然後在空格之後然後再接標題即可. 至於 H1/H2 用底線表示的方法在老式的 README 檔案很常見, 底線長度也是很自由的, 要多長都可以.
粗體斜體
斜體
斜體字語法是這樣
*我是斜體字*
輸出結果: 我是斜體字
也可以是這樣
_我是斜體字_
輸出結果: 我是斜體字
粗體
粗體字語法是這樣
**我是粗體字**
輸出結果: 我是粗體字
也可以是這樣
__我是粗體字__
輸出結果: 我是粗體字
粗斜體
粗斜體字語法是這樣
***我是粗斜體字***
輸出結果: 我是粗斜體字
也可以是這樣
___我是粗斜體字___
輸出結果: 我是粗斜體字
分隔線
以下都是產生分隔線的語法
* * *
***
*****
- - -
---
---------------------------------------
引述
有時候可能需要把某大師(濕)或是某小白講的話原封不動標註起來就會用到
語法是這樣
> 句子
結果就是
句子
看起來是不是很像 e-mail 的引述呢?
你可以選擇一個段落只用一個 > 符號, 也可以每行都用一個 > 符號
例如
> 我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段
結果就是
我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段
也可以這樣
> 我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段
> 我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段
> 我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段
結果就變這樣
我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段
我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段
我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段我是一段
想要有層級也可以
> 我是第一層
>> 我是第二層
>>> 我是第三層
結果就變這樣
我是第一層
我是第二層
我是第三層
引述還可以再參雜 markdown / html 語法.
清單
無順序清單可以是這樣
+ 第一項
+ 第二項
+ 第三項
結果
- 第一項
- 第二項
- 第三項
也可以是這樣
- 第一項
- 第二項
- 第三項
結果
- 第一項
- 第二項
- 第三項
也可以像這樣
* 第一項
* 第二項
* 第三項
結果
- 第一項
- 第二項
- 第三項
有順序的清單是這樣
1. 第一項
2. 第二項
3. 第三項
結果
- 第一項
- 第二項
- 第三項
也可以是這樣
1. 第一項
1. 第二項
1. 第三項
結果
- 第一項
- 第二項
- 第三項
也可以是這樣
100. 第一項
1. 第二項
27. 第三項
結果
- 第一項
- 第二項
- 第三項
清單也可以有層級, 就用空格或 tab 作分級即可
+ 第一層
- 第二層
1. 第三層
結果就變成
- 第一層
- 第二層
- 第三層
- 第二層
連結
連結可以放在內文中就像這樣
我是句首[Geo 的雜記](http://geo-work-tw.blogspot.tw/)我是句尾
結果就變成
我是句首Geo 的雜記我是句尾
也可以像論文一樣用參考的
我是第一句[1]
我是第二句[連結二][2]
我是第三句 [連結三] []
[1]: (http://www.yahoo.com.tw) "台灣雅虎"
[2]: http://www.google.com.tw (google 大神)
[連結三]: <http://www.ruten.com.tw>
結果就變成
表格
表格也很簡單, 語法就像當年在 README 表格的畫法類似
|物品 | 數量 |
|------ | ----- |
|馬克杯 | 一個 |
|手機 | 一隻 |
|充電器 | 10 個 |
結果就變成
| 物品 | 數量 |
|---|---|
| 馬克杯 | 一個 |
| 手機 | 一隻 |
| 充電器 | 10 個 |
也可以這樣
物品 | 數量
------- | -----
馬克杯 | 一個
手機 | 一隻
充電器 | 10 個
結果就變成
| 物品 | 數量 |
|---|---|
| 馬克杯 | 一個 |
| 手機 | 一隻 |
| 充電器 | 10 個 |
也可以設定對齊點
物品 | 數量 | 價錢
:------------ | ------------: | :--------------:
馬克杯 | 一個 | 100 元
手機 | 一隻 | 89999 元
充電器 | 10 個 | ?
:---- 為靠左 | ----: 為靠右 | :----: 為置中
結果就變成
| 物品 | 數量 | 價錢 |
|---|---|---|
| 馬克杯 | 一個 | 100 元 |
| 手機 | 一隻 | 89999 元 |
| 充電器 | 10 個 | ? |
| :—- 為靠左 | —-: 為靠右 | :—-: 為置中 |
程式碼
在行首空四格或是一個Tab就代表這整行是程式碼, markdown 編輯器不會更動他的格式, 所以打的字是甚麼出來就是甚麼
例如
Tab程式碼
就變成
程式碼
也可以用`去標記內文的程式碼, 例如像函式名稱
例如
`printf` 是 C 語言列印函式
結果
printf 是 C 語言列印函式
目錄
語法很簡單, 只要在任何地方插入
[TOC]
結果就像這樣
留言
張貼留言