All Articles

Notes about writting Markdown Articles on GitHub Pages

總共有3大種Markdown語法, 以下1~3跟GitHub相關

  1. GitHub Flavored Markdown (修改於 kramdown) + fenced code blocks + Syntax Highlight(<-不知那一個套件). GitHub uses what we’re calling “GitHub Flavored Markdown” (GFM) for messages, issues, and comments.. GFM使用說明:
  2. GitHub 的線上看到的Readme.md及其Preview,部份的GitHub Flavored Markdown.
  3. Github Pages 用的: kramdown + fenced code blocks and 部份的syntax highlighting of GitHub Flavored Markdown.
  4. 第三大種: 其他非 kmarkdown 的 標準Markdown. 大部份網頁版 Markdown , Markdown軟體 或是Atom等Markdown外掛皆為這種. 這三種(1,3,4)皆有大小不等的差異。

Front Matter

GitHub Page使用的Jekyll有所謂的Front Matter,可以在文章裡面加上如下的Yaml設定, 客製化文章一些資料, 比如說 layout, title, tag, date 等. 如果不指定則像是文章名稱會預設用檔名(字首大寫). E.g. 2016-01-01-文章名.md. posts資料夾裡的文章檔名一定要帶有時間,

title: "It is a cat."



  1. 若要測試寫好的.md/.markdown檔,若要100%確定效果,可以

    1. 在本地端跑 Jekyll
    2. 或是 來測效果,此兩者皆是用Ruby寫的 kramdown.
    3. 使用 Atom的 Package,
  2. 換一個段落的方法

    1. 空一行
    2. 第一行結尾留兩個空白
  3. inline code block:使用兩個前導字元包起來,e.g.


  4. multiple line code block, 可使用四個空白 或是`(Fenced code blocks)的做法, 參考

  5. 語法高亮度的清單(不確定正確):,, 有人說別的Blog(e.g. Hexo)所使用的Markdown沒有支持Github用的`jascript這種

  6. 沒有支援ES6的語法高亮度.

  7. 在 code block or inline code 中打出 ` 符號的方法., So I’ve found that using 4 backticks as opening and closing deliminators does the trick:

About Fenced code block

  1. Syntax highlighting of GitHub Flavored Markdown . It uses `
  2. Fenced code block of Kramdown. It uses ~~~.

GitHub Pages and some/all markdown files on GitHub can accept these two types and show correctly. But this atom package only handles Kramdown type(~). Please keep in mind, and my opinion is to use ~. Also They both support non-fenced standard code block (4 indent) and single line code span.


  1. list要視為新的段落,所以要空一行等動作.
  2. 多層list(Sub list). 要用四個空格來縮排
  3. number後面要加文字才行, 不能直接換行接sub list
  4. GitHub page 不支援 code block的 語法高亮度在 list中
  5. list裡面有多行code , 一定要用四個空格
  6. list裡面包multiple code block, 一定要空一行
Published 19 Jul 2016