github flavored markdown简介

最新推荐文章于 2024-09-03 09:18:52 发布

清晰编程

最新推荐文章于 2024-09-03 09:18:52 发布

阅读量1.1k

点赞数 30

分类专栏：公众号文章标签： github markdown

本文链接：https://blog.csdn.net/wannianchuan/article/details/134882256

版权

公众号专栏收录该内容

199 篇文章 2 订阅

订阅专栏

什么是GitHub Flavored Markdown?

GitHub Flavored Markdown，通常缩写为GFM，是目前在GitHub.com和GitHub Enterprise上支持用户内容的Markdown方言。

这个基于CommonMark Spec的正式规范定义了这种方言的语法和语义。

GFM是CommonMark的严格超集。所有在GitHub用户内容中支持的、原始CommonMark Spec中没有指定的功能因此被称为扩展，并突出显示。

虽然GFM支持广泛的输入，但值得注意的是，GitHub.com和GitHub Enterprise在将GFM转换为HTML后执行额外的后处理和消毒，以确保网站的安全性和一致性。

什么是Markdown?

Markdown是一种用于编写结构化文档的纯文本格式，基于在电子邮件和Usenet帖子中指示格式的约定。它由John Gruber(在Aaron Swartz的帮助下)开发，并于2004年以语法描述和Perl脚本(Markdown.pl)的形式发布，用于将Markdown转换为HTML。在接下来的十年里，许多语言开发了数十种实现。一些扩展了原始的 Markdown 语法，增加了脚注、表格和其他文档元素的约定。一些允许 Markdown 文档以 HTML 以外的格式呈现。Reddit、StackOverflow 和 GitHub 等网站有数百万人使用 Markdown。Markdown 开始被用于 Web 之外，用于编写书籍、文章、幻灯片、信件和讲义。

Markdown 与许多其他轻量级标记语法的区别在于它的可读性，这些语法通常更容易编写。正如 Gruber 所写的：

Markdown 格式化语法的首要设计目标是使其尽可能可读。其理念是 Markdown 格式的文档应该可以按原样发布，就像纯文本一样，而不像它被标记了标签或格式化说明。

这一点可以通过比较 AsciiDoc 的示例和 Markdown 的等效示例来说明。

以下是 AsciiDoc 手册中的一个示例：

1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.

2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.

a. This list is nested and does not require explicit item
continuation.
+
This paragraph is part of the preceding list item.

b. List item b.

This paragraph belongs to item two of the outer list.
--

这里是 Markdown 格式的对应内容：

1.  List item one.

    List item one continued with a second paragraph followed by an
    Indented block.

        $ ls *.sh
        $ mv *.sh ~/tmp

    List item continued with a third paragraph.

2.  List item two continued with an open block.

    This paragraph is part of the preceding list item.

    1. This list is nested and does not require explicit item continuation.

       This paragraph is part of the preceding list item.

    2. List item b.

This paragraph belongs to item two of the outer list.

AsciiDoc 版本可以说更容易编写。你不需要担心缩进。但 Markdown 版本更容易阅读。列表项的嵌套在源代码中是显而易见的，而不仅仅是在处理后的文档中。

为什么需要规范？

John Gruber对Markdown语法的规范性描述并没有明确规定语法。下面是一些它没有回答的问题的例子：

1. 子列表需要多少缩进？规范说，延续段落需要缩进四个空格，但对子列表没有完全明确。很自然地，我们认为它们也必须缩进四个空格，但Markdown.pl并不要求这样做。这几乎不是一个“特殊情况”，在实际文档中，实现在这个问题上的差异经常会给用户带来意外。(参见John Gruber的评论。)

2. 在块引号或标题前需要空行吗？大多数实现并不需要空行。然而，这可能会导致硬包装文本中出现意想不到的结果，并且在解析中产生歧义(请注意，一些实现将标题放在 blockquote 中，而另一些则没有)。

(John Gruber 也表示支持要求空行。)

3. 在缩进代码块之前需要空行吗？(Markdown.pl 要求它，但文档中没有提到这一点，而一些实现不需要它。)

paragraph
    code?

4. 确定列表项何时被 <p> 标签包裹的确切规则是什么？列表可以部分“松散”和部分“紧凑”吗？我们应该如何处理这样的列表？

  1. one

  2. two
  3. three

还是？

  1.  one
      - a

      - b
  2.  two

(John Gruber 对此有一些相关评论。)

5. 列表标记可以缩进吗？有序列表标记可以右对齐吗？

  8. item 1
  9. item 2
  10. item 2a

6. 这是一个列表，在第二个项目中有一个主题分隔符，还是两个列表由主题分隔符分隔？

  * a
  * * * * *
  * b

7. 当列表标记从数字到项目符号时，我们有两个列表还是一个列表？(Markdown语法描述建议两个列表，但perl脚本和其他许多实现产生一个列表。)

  1. fee
  2. fie
  -  foe
  -  fum

8. 内联结构的标记的优先级规则是什么？例如，下面是一个有效的链接，还是代码范围优先？

  [a backtick (`)](/url) and [another backtick (`)](/url).

9. 强调和强强调的标记的优先级规则是什么？例如，下面应该如何解析？

  *foo *bar* baz*

10. 块级和内联级结构之间的优先级规则是什么？例如，下面应该如何解析？

  - `a long code span can contain a hyphen like this
    - and it can screw things up`

11. 列表项可以包含段落标题吗？(Markdown.pl不允许这样做，但允许blockquote包含标题。)

  - # Heading

12. 列表项可以为空吗？

  * a
  *
  * b

13. 可以在块引号或列表项中定义链接引用吗？

  > Blockquote [foo].
  >
  > [foo]: /url

14. 如果同一引用有多个定义，哪个优先？

  [foo]: /url1
  [foo]: /url2

  [foo][]

在没有规范的情况下，早期的实现者会参考 Markdown.pl 来解决这些歧义。但是 Markdown.pl 有很多 bug，在很多情况下会给出明显糟糕的结果，所以它不是规范的满意替代品。

由于没有明确的规范，实现差异很大。因此，用户经常惊讶地发现，在一个系统(比如 GitHub wiki)上以一种方式呈现的文档在另一个系统(比如使用 pandoc 转换为 docbook)上呈现的方式不同。更糟糕的是，由于 Markdown 中没有任何东西被视为“语法错误”，这种差异往往不会立即被发现。

为了解决这个问题，GitHub制定了GitHub Flavored Markdown规范，并编写了相应的文档。文档试图明确地指定 Markdown 语法。它包含许多 Markdown 和 HTML 并排的示例。这些示例旨在充当一致性测试。附带的脚本 spec_tests.py 可以用来针对任何 Markdown 程序运行测试：

python test/spec_tests.py --spec spec.txt --program PROGRAM

由于本文档描述了如何将 Markdown 解析为抽象语法树，因此使用语法树的抽象表示而不是 HTML 是有意义的。但是 HTML 能够表示我们需要做出的结构区分，并且选择使用 HTML 进行测试，使得在不编写抽象语法树渲染器的情况下对实现运行测试成为可能。

文档是从一个文本文件 spec.txt 生成的，该文件使用 Markdown 编写，并为并行测试添加了一个小的扩展。脚本 tools/makespec.py 可以用于将 spec.txt 转换为 HTML 或 CommonMark(然后可以转换为其他格式)。

文档地址：GitHub Flavored Markdown Spec

欢迎关注微信公众号：文本魔术，了解更多