Zohar's blog

GFM(Github Flavored Markdown) 使用笔记

TOPMarkdownMarkdownGFM

github 引入了 markdown 并对之进行拓展，这种由 github 衍生出来的 markdown 称为 GFM(Github Flavored Markdown)。

Markdown 不是想要取代 HTML，甚至也没有要和它相近，它的语法种类很少，只对应 HTML 标记的一小部分。Markdown 的构想不是要使得 HTML 文档更容易书写。在我看来， HTML 已经很容易写了。Markdown 的理念是，能让文档更容易读、写和随意改。HTML 是一种发布的格式，Markdown 是一种书写的格式。就这样，Markdown 的格式语法只涵盖纯文本可以涵盖的范围—— John Gruber

目录

1 原生 markdown 语法

1.1 区块元素

1.1.1 段落

使用 markdown 必须对 行 与 段 有一个清晰的认识，markdown 旨在让书写变得清晰明了，所以段落和行的概念在 markdown 中十分重要。

  • 文本行 : 即一行文字，markdown 中换行必须进行手动操作（两个空格加换行符），自动换行将会变成一个空格

      <!-- aaaaa 后无空格： -->
  aaaaa
  bbbbb

  <!-- aaaaa 后两个空格： -->
  aaaaa  
  bbbbb

    aaaaa bbbbb

    aaaaa
    bbbbb

  • 段　落 : 由数行文字成一段，markdown 中由空行划分段落

      <!-- aaaaa、bbbbb 后面都接两个空格，因此会换行，但它们都是同一段落 -->
  aaaaa  
  bbbbb  
  ccccc

  <!-- aaaaa、bbbbb、ccccc 之间都间隔空行，因此划分为三段 -->
  aaaaa

  bbbbb

  ccccc

    aaaaa
    bbbbb
    ccccc

    aaaaa

    bbbbb

    ccccc

1.1.2 标题

  • 底线形式(Setext): 标题下方插入任意数量的 = (一级标题）

  • 井号形式(atx) : 标题行首插入1至6个 #加上空格，构成一至六级标题

      一级标题
  =

  # 一级标题
  ## 二级标题
  ### 三级标题
  #### 四级标题
  ##### 五级标题
  ###### 六级标题

1.1.3 引用区块

段落行首插入 > 。插入多个 > 可在区块内实现多重嵌套

<!-- aaa 后面接两个空格后换行 -->
>aaa  
bbb

<!-- aaa 后面无空格换行 -->
>aaa
bbb

<!-- aaa 后接两个空格换行 -->
>aaa  
>bbb

<!-- aaa 后无空格换行 -->
>aaa
>bbb

aaa
bbb

aaa bbb

aaa
bbb

aaa bbb

1.1.4 列表

  • 无序列表 : 行首插入 *、+ 或 - ，加上一个空格 ` ` 可生成无序列表项目，可通过制表符进行多重嵌套

      * 项目 1

  * 项目 2

  + 项目 3
      + 项目 3.1
          + 项目 3.1.1

  - 项目 4

    • 项目 1

    • 项目 2

    • 项目 3
      • 项目 3.1
        • 项目 3.1.1
    • 项目 4

  • 有序列表 : 数字. + ` `可生成相应编号列表项目，可通过制表符进行多重嵌套

      1. 项目 1

  2. 项目 2

    1. 项目 1

    2. 项目 2

1.1.5 代码块

  • 原生 MD：使用一个制表符（4个空格）进行缩进即可生成代码区块

          package main
      import "fmt"
      func main(){
          fmt.printf("hello go!")
      }

      package main
  import "fmt"
  func main(){
      fmt.printf("hello go!")
  }

  • GFM：围栏式代码区块，在代码上下一行使用三个反引号 ```， 并在第一行反引号后自定义代码语种，支持相应语种的代码高亮

      ```go
  package main
  import "fmt"
  func main() {
      fmt.printf("hello go!")
  }
  ```　

      package main
  import "fmt"
  func main(){
      fmt.printf("hello go!")
  }

      ~~~go
  package main
  import "fmt"
  func main() {
      fmt.printf("hello go!")
  }
  ~~~

      package main
  import "fmt"
  func main() {
      fmt.printf("hello go!")
  }

      ~~~
  package main
  import "fmt"
  func main() {
      fmt.printf("hello go!")
  }
  ~~~
  {: .language-go}

      package main
  import "fmt"
  func main() {
      fmt.printf("hello go!")
  }

1.1.6 分割线

在一行中使用3个及以上的 * 、- 可生成分割线， 符号之间允许有空格但不允许有任何字符，三个以上 - 推荐用 - - - 表示，防止产生与标题相同的歧义

第一段
- - -
第二段
***
第三段

第一段落

第二段落

第三段落

1.2 行内元素

1.2.1 强调

  • 斜体 : 用一个 * 或 _ 包裹，紧贴被强调文本

  • 粗体 : 用两个 * 或 _ 包裹，紧贴被强调文本

      *斜体文本*  
  _斜体文本_  
  **粗体文本**  
  __粗体文本__

    斜体文本
    斜体文本
    粗体文本
    粗体文本

1.2.2 链接

  • 行内式 :

    1. [显示文本](链接 "title")

    2. [链接][显示文本 title]

  • 参考式 :

    1. [显示文本][唯一id]，然后于文章任意处起一行: [唯一id]: 链接 "title"

    2. [显示文本 title]，然后于文章任意处起一行：[显示文本 title]: 链接

  • 自动式 : <链接>, 必须标明通讯协议

  • 标题锚 : [显示文本](#某个标题)

      有问题？有[必应](https://www.bing.com "bing.com")！  
  有问题？别[百度][1]！  
  可能的话，用 <https://www.google.com> 好一点。  
  [脚注](#212-脚注)，这是一个指向其他标题的**标题锚**
  ...
  [1]: https://www.baidu.com

    有问题？有必应！
    有问题？别百度！
    可能的话，用 https://www.google.com 好一点。
    脚注，这是一个指向其他标题的标题锚

1.2.3 行内代码

用`包裹代码

不要使用任何 `<html>` 标签

不要使用任何 <html> 标签

1.2.4 图片

类似 链接 语法，在其之前添加 ! 即可。

  • 行内式 : ![](图片链接 "图片标签")

  • 参考式 : ![][唯一id]，然后于文章任意处起一行 : [唯一id]: 图片链接 "图片标签"

      ![site icon](https://zoharyip.club/favicon.ico "site icon")  
  ![site icon][2]
  ...
  [2]: https://zoharyip.club/favicon.ico

    site icon
    site icon

2 GFM 拓展语法记录

2.1 区块元素

2.1.1 围栏式代码

在代码上下一行使用三个反引号 ```, 并在第一行反引号后自定义代码语种，支持相应语种的代码高亮
具体实例看上文 GFM 代码块

2.1.2 脚注

This is a text with footnote[^1]
...
[^1]: Here is the footnote 1 definition.

This is a text with footnote1

2.1.3 不同的列表嵌套方法

每缩进指定数量空格，嵌套一层列表，空格数量可以自行设定

* 项目一
* 项目二
  * part a
  * part b
  * part c
    * chapter one
    * chapter two
* 项目三
  • 项目一
  • 项目二
    • part a
    • part b
    • part c
      • chapter one
      • chapter two
  • 项目三

2.1.4 表格

表格为横行竖列，首行为标题，第二行指定表格内容布局，第三行开始为表格数据，示例如下：

  • 示例：

      标题一 | 标题二 | 标题三
  - | :-: | -:
  a | 一 | 1
  b | 二 | 2
  c | 三 | 3.1 task1<br/>3.2 task2<br/>3.3 task3<br/>
  == | == | ==
  尾行 | 即表格的最后一行
    标题一 标题二 标题三
    a 一 1
    b 二 2
    c 三 3.1 task1
    3.2 task2
    3.3 task3
    尾行 即表格的最后一行  

  • 解析：

    要素 含义
    | 分割表格每一列的标志
    第一行 首行为标题行
    第二行 第二行控制对齐
    :-- 左对齐
    :-: 居中
    --: 右对齐
    == 分割表格 foot 的标志

2.1.5 任务列表

- [x] Task 1
- [ ] Task 2
* [x] Task a
* [ ] Task b
  • Task 1
  • Task 2
  • Task a
  • Task b

2.1.6 数学公式

可以使用 MathJax 插件，但如果需要在 README.md 文件中展示数学公式，缓兵之计是使用数学公式的图片：

  1. 访问 codecogs Latex 公式生成器

  2. 输入你所要的 Latex 表达式

    输入Latex表达式

  3. 复制生成的 URL 或直接下载图片

    复制URL

  4. 链接该图片到 md 文件中

     ![方程组](https://latex.codecogs.com/gif.latex?$$&space;\begin{cases}&space;a_1x&plus;b_1y&plus;c_1z=d_1\\&space;a_2x&plus;b_2y&plus;c_2z=d_2\\&space;a_3x&plus;b_3y&plus;c_3z=d_3\\&space;\end{cases}&space;$$ "方程组")

  5. 效果

    方程组

2.2 行内元素

2.2.1 emoji 表情

如 :smile: 为 :smile: , :kissing: 为 :kissing:
具体表情参考GFM 表情列表

2.2.2 删除线

用两个 ~ 包裹被删除文字。如 ~~被删除文字~~ 为 被删除文字。

3 Jekyll 拓展语法

这些语法针对使用 jekyll 框架搭建的博客系统, 其语法规则在 github 上并不会生效

3.1 目录

* TOC
{:toc}

效果见文首目录

3.2 mathjax

开启: 于文章头部添加 mathjax: true

If $$(a \ne 0)$$, the result of $$(ax^2 + bx + c = 0)$$ are $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$

If , the result of are

3.3 mermaid

文档：Mermaid

<div class="mermaid">
sequenceDiagram
    Alice-->>John: Hello John, how are you?
    John-->>Alice: Great!
</div>
sequenceDiagram Alice-->>John: Hello John, how are you? John-->>Alice: Great!

  1. Here is the footnote 1 definition. ↩