Markdown小记

用了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 规范中指定的功能，因此被称为扩展，并作为此类突出显示。

它的解析库是cmark-gfm，采用C编写，有各种语言的绑定：

https://github.com/github/cmark-gfm

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 的简洁和易用性。

编辑器与实现

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

编辑器

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

VSCode（有多种扩展，Office Viewer）
MarkText
Typora（转正收费软件后，基本不考虑了）
...

实现

markdown-it

markdown-it 是基于 JavaScript 的 Markdown 解析器。它完全兼容 CommonMark 规范，并且支持扩展 Markdown 语法（如 GFM、表格、脚注等）。

它在python下的移植叫做：markdown-it-py

Python-markdown

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

markdown-katex 支持 katex
md-mermaid 支持 mermaid

Python-markdown的生态极为丰富。别的实现有的功能，多数都能找到对应扩展。

kramdown

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

扩展

混战的markdown有各种扩展。关注一下 katex 和 mermaid 等

metadata、front matter？？

python-markdown支持在markdown文件头部有类似下面的meta信息，文档中叫做meta data：

Title:   My Document
Summary: A brief description of my document.
Authors: Waylan Limberg
         John Doe
Date:    October 2, 2007
blank-value:
base_url: http://example.com

This is the first paragraph of the document.

MultiMarkdown支持在markdown文件头部有类似下面的meta信息，文档中叫做meta data：

Title:    A Sample MultiMarkdown Document  
Author:   Fletcher T. Penney  
Date:     February 9, 2011  
Comment:  This is a comment intended to demonstrate  
          metadata that spans multiple lines, yet  
          is treated as a single value.  
CSS:      http://example.com/standard.css

jekyll支持文件头部包含YAML front matter block。github的pages也使用front matter，注意格式---：

---
layout: post
title: Blogging Like a Hacker
---

gitlab也支持front matter，但似乎没明确它是不是yaml：

---
title: "Page title"
other_attribute: "see other sections for what's valid"
---

pdandoc中有所谓的title block：

% title
% author(s) (separated by semicolons)
% date

pandoc也支持yaml metadata block，注意格式，以---开头，且用---或...表示该block的结束：

---
title: The document title
author:
- name: Author One
  affiliation: University of Somewhere
- name: Author Two
  affiliation: University of Nowhere
...

markdown-it生态下，各种扩展更是层出不穷，基本上以yaml为主。有的要求三个或以上-开头或结尾，有的要求---开头，用---或...结尾

---
valid-front-matter: true
---

Katex

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

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

KaTeX 的主要特点：

速度快：KaTeX 是目前已知的最快的数学排版库之一，能够几乎即时地渲染数学公式
自渲染：KaTeX 不依赖于任何外部服务或插件，它在用户的浏览器中直接渲染公式。
易于使用：只需将 KaTeX 的 JavaScript 和 CSS 文件包含在你的网页中，就可以开始渲染数学公式了。
高质量的排版：KaTeX 生成的数学公式外观精美，支持高分辨率显示。

与MathJax对比

特性	KaTeX	MathJax
渲染速度	非常快，适合需要快速渲染的场景	较慢，尤其是在处理复杂公式时
服务器依赖	无需服务器支持，完全在客户端运行	通常在客户端运行，但也可以配置服务器端渲染
易用性	简单，引入 CSS 和 JavaScript 即可使用	配置较复杂，但提供丰富的自定义选项
LaTeX 兼容性	支持的 LaTeX 命令较少，主要是基本和常用命令	支持广泛的 LaTeX 命令和功能，包括复杂宏和扩展
浏览器兼容性	较好，特别是在现代浏览器中	非常好，包括对老旧浏览器的支持
交互性	较少的交互性支持	强大的交互性支持，包括可点击的公式等
文档和社区支持	文档清晰，社区活跃但相对较小	详尽的文档和庞大的用户社区

Gitlab支持

Gitlab 支持katex。

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

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

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

python-markdown支持

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

行内公式：需要放置在美元符号和反引号构成的分隔符之间($`...`$)
独立公式：放置到声明为 math的代码块中。比如：

标记如下代码为 math

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

将会：

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

图表 mermaid

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

标记如下代码为mermaid

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

将会

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

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

python中的markdown有对merimad的扩展支持

https://pypi.org/project/markdown-mermaidjs/

参考

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)
https://github.com/markdown-it/markdown-it
https://github.com/executablebooks/markdown-it-py
https://github.com/github/cmark-gfm
atx, the true structured text format (aaronsw.com)
https://github.com/Vanessa219/vditor
MarkText Markdown Reference | Markdown Guide
Flowcharts Syntax | Mermaid
Math in MarkDown · cben/mathdown Wiki · GitHub

1+1=10

记记笔记，放松一下...