用了10多年Markdown，却一直没有正经地看过它。每次换edit后，查看之前写的东西，总有些格式问题。各个编辑器介绍自己支持的一堆东西，又看不懂...

什么是Markdown？

Markdown 语法主要受 Swartz's 于 2002年创建的 atx 影响。

Markdown 是一种用于编写结构化文档的纯文本格式。它由 John Gruber 开发（得到 Aaron Swartz 的帮助），并于 2004 年以语法描述和一个 Perl 脚本（Markdown.pl）的形式发布，该脚本用于将 Markdown 转换成 HTML。

在接下来的十年中，许多语言中开发了数十种实现方式。其中一些扩展了原始 Markdown 语法，增加了脚注、表格和其他文档元素的约定。像 Reddit、StackOverflow 和 GitHub 这样的网站有数百万人使用 Markdown。Markdown 还开始被用于网络之外的地方，用于编写书籍、文章、幻灯片、信件和讲义。

Markdown 与许多其他轻量级标记语法相比的特点是其可读性。正如 Gruber 所写：

Markdown 格式语法的首要设计目标是尽可能提高可读性。其理念是，Markdown 格式的文档应当能够以纯文本的形式发布，而看上去不像是用标签或格式指令标记过。（http://daringfireball.net/projects/markdown/）

Markup 与 Markdown（up ↑ 与 down ↓ )？

• Markup（标记语言）指的是一种包含“标记”的编程语言，用于处理和定义文本的结构与样式。最常见的标记语言是 HTML（HyperText Markup Language），用于创建和设计网页。

• Markdown 是一种轻量级标记语言，用简单的标记语法来格式化文本。它的目标是使文档易于阅读、易于编写。

CommonMark、GFM、FLFM、MMD、... 都是什么鬼？

John Gruber 对 Markdown 语法的规范描述，很多地方不够严谨（有二义性），对于各种Markdown工具的实现，是一个很大的挑战。而且Markdown.pl脚本，本身也有很多bug，可参考性不够。

CommonMark

因为原始的 Markdown 语法由 John Gruber 设计时留下了一些模糊和不一致的地方，不同的解释器可能会对同样的 Markdown 文本产生不同的解析结果。这种差异可能导致文档在不同平台上的显示效果不同，从而影响内容的一致性和专业性。

CommonMark 试图成为 Markdown 语法的标准化版本，通过提供统一的规范来帮助开发者和内容创作者避免兼容性问题。它不是要替代原始的 Markdown，而是希望通过解决其局限性来增强 Markdown 的实用性和可靠性。

因为Gruber不同意这个标准化的工作，使用Markdown字样，最终Standard Markdown is now Common Markdown 。

CommonMark 是一种开源的 Markdown 规范，旨在解决不同 Markdown 解释器之间存在的语法不一致问题。

• 明确和一致：CommonMark 提供了一套严格定义的规范，明确了 Markdown 语法的每一个方面，减少了解释的歧义。

• 跨平台兼容：它旨在确保 Markdown 文档在任何支持 CommonMark 的平台上都能有一致的解析和显示效果。

GFM (GitHub Flavored Markdown)

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

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

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

GLFM(Gitlab Flavored Markdown)

GitLab Flavored Markdown 包括以下内容：

• 基于 CommonMark 规范的核心 Markdown 功能。

• 来自 GitHub Flavored Markdown 的扩展。

• 专为 GitLab 制作的扩展。

MMD（MultiMarkdown)

MultiMarkdown 是在 CommonMark 出现之前开发的，并不完全符合 CommonMark 标准。

MultiMarkdown (MMD) 是 Markdown 的一个扩展，它增加了对表格、脚注、交叉引用等复杂内容的支持，使其更适用于学术写作和专业出版。MultiMarkdown 旨在保持 Markdown 的简洁性和易用性，同时增加额外的功能以处理更复杂的文档结构。

MultiMarkdown 特别适合需要编写结构复杂文档的场景，如学术论文、书籍、研究报告等。由于其对多种输出格式的支持，它也非常适合需要将内容转换成特定格式的出版流程。

PHP Markdown Extra

PHP Markdown Extra 基于早期的 Markdown 实现，并且加入了一些额外的功能，如表格、定义列表和脚注等。并不符合 CommonMark 规范

PHP Markdown Extra 是一个基于 PHP 的 Markdown 解析器，它在原始 Markdown 实现的基础上添加了一些额外的功能。这个扩展由 Michel Fortin 开发，旨在增加一些对专业和学术写作非常有用的特性，同时保持 Markdown 的简洁和易用性。

扩展

...

Katex

在MarkDown中添加公式支持，也是一团混战：Math in MarkDown · cben/mathdown Wiki · GitHub，只能条感兴趣的简单看看。

KaTeX 是一个快速的数学排版库，它可以在网页上渲染高质量的数学公式。KaTeX 是由 Khan Academy 开发的，它的主要目的是为了在网页上快速渲染数学公式，以改善用户体验。

KaTeX 的主要特点：

• 速度快：KaTeX 是目前已知的最快的数学排版库之一，能够几乎即时地渲染数学公式

• 自渲染：KaTeX 不依赖于任何外部服务或插件，它在用户的浏览器中直接渲染公式。

• 易于使用：只需将 KaTeX 的 JavaScript 和 CSS 文件包含在你的网页中，就可以开始渲染数学公式了。

• 高质量的排版：KaTeX 生成的数学公式外观精美，支持高分辨率显示。

与MathJax对比

Gitlab支持

Gitlab 支持katex。

行内公式：需要放置在美元符号和反引号构成的分隔符之间($`...`$)或者放置到美元符号之间 ($...$) 。

独立公式：放置到两个美元符号构成的分隔符之间($$...$$)，或者声明为math的代码块中。

Marktext默认不支持math代码块的写法，但是可以通过preferences -> Markdown-> "GitLab compatibility"选项打开【但是打开之后，Marktext的typewriter模式下又会自动把识别出的math转成$$...$$写法，挺不好玩的】。另外，即使打开，($`...`$)写法仍然不支持！！

python-markdown支持

python-markdown通过插件markdown-katex来支持katex。它支持的Gitlab使用的如下语法：

• 行内公式：需要放置在美元符号和反引号构成的分隔符之间($`...`$)

• 独立公式：放置到声明为math的代码块中。比如：

$$f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi$$

getpelican支持？

getpelican使用的python-markdown，理论上用markdown-katex就行了。启用方式：

# pelicanconf.py
MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
        'markdown_katex': {'no_inline_svg': False, 'insert_fonts_css': True}
    },
    'output_format': 'html5',
    }

注意，至此只添加了markdown——katex，之所以写这么多，是因为其他的是getplican的默认值，不能直接覆盖MARKDOWN变量，不然table、code 都会解析不正常。

除了这个方式之外， 还有一个 pelican-katex 也可以用来支持katex（使用安装node.js以便于它运行katex.js文件），运行完之后，发布时不需要js文件，只需要对应的css文件。

• 行内公式：需要放置在美元符号之间($...$)

• 独立公式：放置到声明为($$...$$)之间。

图表 mermaid

Mermaid 允许开发者和文档作者通过简洁的文本描述来生成图表和可视化表示，如流程图、序列图、甘特图等。它是专为简化在 Markdown 文件和网页中创建复杂图表的过程而设计的。

graph TD;
    A --> B;
    A --> C;
    B --> D;
    C --> D;

注意对比PlainUML。PlainUML是一个工具，允许用户使用纯文本语言来创建图表。它支持多种图表类型，包括序列图、用例图、类图、活动图、组件图、状态图等。

编辑器与实现

缺乏统一标准，实现各个不同...

编辑器

因为缺少同一个的规范，以及各种各样的扩展的存在。各个编辑器对Markdown支持也各不相同...

• MarkText

• VSCode

• Typora（转正收费软件后，基本不考虑了）

• ...

其他语言实现

Python-markdown

这不是一个 CommonMark 的实现；也不是在尝试成为一个！Python-Markdown 是在 CommonMark 规范发布很久之前开发的，并且一直（大部分时间）遵循原始参考实现的语法规则和行为。没有做出任何调整来适应 CommonMark 所建议的变更。

• markdown-katex 支持 katex

• md-mermaid 支持 mermaid

kramdown

Kramdown 是一个免费的、纯 Ruby 编写的 Markdown 解析器和转换器。它被设计用来解析某些 Markdown 方言，并将其转换成多种输出格式，比如 HTML。

参考

• Daring Fireball: Markdown Syntax Documentation

• GitHub Flavored Markdown Spec

• GitLab Flavored Markdown (GLFM) | GitLab

• https://spec.commonmark.org/

• Markdown - Wikipedia

• Syntax | kramdown

• MultiMarkdown v6 Syntax Guide (rawgit.com)

• PHP Markdown Extra (michelf.ca)

• atx, the true structured text format (aaronsw.com)

• MarkText Markdown Reference | Markdown Guide

• Flowcharts Syntax | Mermaid

• Math in MarkDown · cben/mathdown Wiki · GitHub