update few notes

# KaTeX

其实早在好几年前 [KaTeX](https://khan.github.io/KaTeX/) 刚出来的时候, 我就有关注这个 MathJax 的代替者. 不过当时好多公式符号都无法加载, 那时甚至矩阵都显示有问题. KaTeX 虽然加载公式速度很快, 但是怕我文章里有公式不能正常显示, 所以还是没有选择使用它. 不过就像很多开源软件一样, 时间能让它们变得越来越好. 诚如前段时间回归 Typecho 重新写博客一样, Markdown 和 MathJax 之间的小 Bug 得到完美解决; 如今 KaTeX 也能独当一面, 可以彻底代替 MathJax 了.

为了方便, 所以还是使用了官方自带的 CDN 的简单配置. 

```html

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.css" integrity="sha384-9tPv11A+glH/on/wEu99NVwDPwkMQESOocs/ZGXPoIiLE8MU/qkqUcZ3zzL+6DuH" crossorigin="anonymous">

<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.js" integrity="sha384-U8Vrjwb8fuHMt6ewaCy8uqeUXv4oitYACKdB0VziCerzt011iQ/0TqlSlv8MReCm" crossorigin="anonymous"></script>

<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/contrib/auto-render.min.js" integrity="sha384-aGfk5kvhIq5x1x5YdvCp4upKZYnA8ckafviDpmWEKp4afOZEqOli7gqSnh8I6enH" crossorigin="anonymous"></script>

```

​其中前两个是 KaTeX的基本配置,第三个是自动加载的插件. 不过之后遇到的  KaTeX 的唯一问题是默认所有公式无论是行间公式还是行内公式都要写在左右各两个美元符号内. 这和其他 LateX, MathJax 的习惯不一致. 所以我还是去看了一下设置, 其实在配置`delimiters` 中修改. 于是我改为如下配置:

```js

<script>

    renderMathInElement(document.body,

   {

              delimiters: [

                  {left: "$$", right: "$$", display: true},

                  {left: "\\[", right: "\\]", display: true},

                  {left: "$", right: "$", display: true},

                  {left: "\\(", right: "\\)", display: false}

              ]

          }

  );

</script>

```

问题并没有因为我把单个美元符号的`display`改为`true`而愉快地被解决, 之后所有行内公式也会被加载为行间公式. 于是我再看到官方文档中有`displayMode`的选项. 不过作者说默认是关闭的, 因为这个选项`true`就是行间公式(公式会变大,且居中). 于是我很开心地加一句 `displayMode: false`, 不过没有任何变化. 

经过排列组合地各种尝试, 我惊奇地发现需要将单美元符号display改为 false, 然后打开 displayMode, 这样看起来完完全全相反的设置竟然"负负得正", 完美解决了这一问题. 撒花~ *★,°*:.☆(￣▽￣)/$:*.°★* 。更改后的设置如下:

```js

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.10.0-rc.1/katex.min.css">

<script src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.10.0-rc.1/katex.min.js"></script>

<script src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.10.0-rc.1/contrib/auto-render.min.js"></script>

<script>

    renderMathInElement(document.body,

   {

              delimiters: [

                  {left: "$$", right: "$$", display: true},

                  {left: "$", right: "$", display: false}

              ]

          }

  );

</script>

```

实际上发现默认的`displayMode`值其实是 true. 最后终于开心地发现博客里的数学公式加载变快了, 同时 KaTeX 和 InstantClick 也没有像 MathJax 一样有时候出现加载到一半(mathjax快速预览)的冲突. 赞!

whzecomjm

2018年7月12日

-----

## 更新 KaTeX4Typecho 插件

今天逛Typecho论坛发现已经有人制作了 [KaTeX4Typecho](https://github.com/vc12345679/KaTeX4Typecho). 不过鉴于我知道 Typecho 1.1 正式版之后它的 Markdown内核 [HyperDown 的更新](/archives/start.html), 之前和其他无论是动态博客还是静态博客都一样存在的 `\` 转义的 bug 得到解决, 所以我们可以开心回归"正常的LaTeX写法".

于是我顺便下载该插件试用以后发现之前的设置不友好, 于是将默认设置更新为 `$ ... $` 表示行内公式, 而 `$$ ... $$`表示行间公式. 这样就和我们平时用的 LaTeX 书写方法一致. 同时顺便也更新了最新的KaTeX 0.10.0, 能支持更多的公式选项. 鉴于原作者不在维护该插件, 我于是fork一下更新了一下, 需要的同学可以从我的[Github仓库](https://github.com/whzecomjm/KaTeX4Typecho)下载安装. 

2018年7月15日

插件一个小Bug, 题目如果出现大括号会自动加载为行间公式. 检测结果是 `\[\]` 等价于 `[]`, 这应该是 Hyperdown不想做的, 只支持美元形式, 其实也更好.

## 国内开源项目 CDN 加速服务的KaTeX 

```html

<link rel="stylesheet" href="https://cdn.bootcss.com/KaTeX/0.10.0-alpha/katex.min.css">

<script src="https://cdn.bootcss.com/KaTeX/0.10.0-alpha/katex.min.js"></script>

<script src="https://cdn.bootcss.com/KaTeX/0.10.0-alpha/contrib/auto-render.min.js"></script>

```

# 不同的 Markdown 语法

这篇文章属于专题的一部分，详见：[Markdown知识贴](https://sspai.com/p/de1c5a00)  

> 原文链接: https://sspai.com/post/37270.

[TOC]

2.1. 原生Markdown

---------------

Markdown语法最早由John Gruber于2004年创立。为了与后来的衍生markdoon语言区别，这里将其称为原生Markdown。虽然现在使用的Markdown与原生Markdown有所不同，但是衍生的众多Markdown语法也沿袭了很多原生Markdown的语法，学习原生的Markdown对学习Markdown大有帮助，特别是理解Markdown的理念。John Gruber在其个人主页中公布了详细的Markdown语法说明，随着Markdown的推广和传播，这份说明也被广泛传播和翻译，下面提供了相关的网址：   

英文原文：[http://daringfireball.net/projects/markdown](http://daringfireball.net/projects/markdown)   

简体中文版：[http://www.markdown.cn](http://www.markdown.cn/)或[http://wowubuntu.com/markdown](http://wowubuntu.com/markdown)   

繁体中文版：[http://markdown.tw](http://markdown.tw/)

原生Markdown将语法分成区块元素和行内元素：

*   区块元素：段落、标题、区块引用、列表（无序和有序）、区块代码、分隔线

*   行内元素：链接、强调（粗体和斜体）、行内代码、图片

可以看出，原生Markdown支持的元素并不多，连表格都不支持，只支持一些基本的元素。

原生Markdown兼容HTML：为了实现一些Markdown不具备的功能，Markdown中可以使用HTML标签。块级标签必须前后空行，且不能被空格或制表符缩进（即不可被嵌套）。另外，块级标签内不能使用markdown语法。行内标签直接使用。

下面是各部分语法说明的笔记：

### 区块元素

**段落**：段落前后空行   

注意：1）段落与文本行不是一个概念，一个段落中可以包含多个文本行，段落内部可以插入两个以上空格然后回车实现强制换行。2）非嵌套的段落不该用空格或制表符`Tab`缩进。

**标题**：

1.  Setext式（底线形式）：标题下行插入任意数量 `=` （最高阶标题）或`-` （第二阶标题）；

2.  Atx式：标题行首插入1到6个 `#` ，对应到标题 1 到 6 阶。   

    注意：1） `#` 与标题文字间有空格。2）行末可选择性插入 `#` 闭合Atx式标题，不要求数量

**区块引用**：每行行首插入 `>`。   

注意：1）也可以只在段落首行插入 `>`。2）`>`后可不接空格。3）插入多个`>`可以实现区块引用多重嵌套。4）可以嵌套段落、标题、列表、区块代码。

**列表**：

1.  无序列表（unordered/bulleted lists）：使用星号（asterisks）`*` 、加号（pluses）`+` 或是减号（hyphens）`-` 作为列表项目标记。

2.  有序列表（ordered/numbered lists）：使用数字加英文句号作为列表项目标记。

注意：1）列表项目标记后接空格。2）作为列表标记的数字不影响最后输出结果。3)列表项目里的文本行可以用最多3个空格进行缩进对齐，但是不影响最后输出。4）如果两个列表项目间被空行分开，那么这两个列表项目会识别为段落，间隔变大。5）可以嵌套列表（文档没描述，实际可行）、段落、区块引用，方法为每行行首使用4个空格或1个制表符（Tab）进行缩进。6）嵌套的段落可以只在首行使用4个空格或1个制表符（Tab）缩进。7）如果不希望数字-英文句号-空格被识别为列表，可以再英文句号前加入反斜杆`\`。

**区块代码**：每行代码使用4个空格或1个制表符进行缩进。

**分隔线**：在新行中插入3个及以上入减号（hyphens）`-`，星号（asterisks）`*`或下划线（underscores）`_`。

### 行内元素

**链接**：

1.  行内式（inline）：`[文字]（URL "Tittle"）`。   

    注意：Tittle可不添加。

2.  参考式（reference）：`[文字][id]` ，然后在文章任意新行，`[id]: URL "tittle"`。   

    注意：1）tittle可不添加。2）id（链接标记，link identifier）可以使用文字字母、数字、空格、标点符号，不区分大小写。3）如果id空置，自动将链接文字视为id。

3.  自动链接：简单的链接或邮箱地址可以直接用尖括号包裹`<链接或邮箱地址>`

**强调**：

1.  强调（默认斜体）：用一个星号`*`或下划线`_`包裹。

2.  重强调（默认粗体）：文字两边用两个星号`*`或下划线`_`包裹。   

    注意：星号与下划线必须紧贴包裹的文字。

**行内代码**：用反引号（backtick quotes）包裹。   

注意：1）起始的反引号之后与结束的反引号之前可放入空格。2）如果在代码中有反引号，需要多个反引号来包裹。

**图片**：

1.  行内式：`![Alt text](scr)`

2.  参考式：`![Alt text][id]`，在任意新行添加`[id]: scr "title"`   

    注意同链接

### 转义

如果希望键入被语法占用的特殊符号，可以在特殊符号前插入反斜线实现转义。

2.2. 衍生Markdown

---------------

自从John Gruber2004年发布Markdown之后，Markdown进入了自由生长的状态，因为创始人John Gruber打自2004年之后就没有更新过Markdown。因为原生Markdown只是一个轻量级的标记语言，很多功能不具备。为了扩充Markdown的功能，很多Markdown拓展语法被开发出来，其中著名的有GFM、PHP Markdown Extra、MultiMarkdown、Pandoc Markdown等等

### 2.2.1. GFM

原生Markdown发布后，最早在程序员圈内流行。由于Markdown的易读易写，而且对程序员很友好（支持区块代码和行内代码），全球最大的代码托管平台Github引入了Markdown，并且对原生Markdown语法进行了拓展，这种衍生Markdown叫做Github Flavored Markdown，简称 GFM 。

与原生Markdown的主要不同：

*   **采用围栏式（Fenced式）区块代码**：在代码的上下一行用3个反引号` ``` `，可选择性定义代码语种，并支持代码高亮。

*   **列表嵌套方法**：改为每次嵌套缩进两个空格。

*   **支持任务列表**：在每个列表项目加入`[ ]`，完成任务用 `[x]`，如：`- [x] 任务说明`。

*   **支持简单表格**

    ```

    |FirstHeader|SecondHeader|

    |-----------|-----------|

    |ContentCell|ContentCell|

    |ContentCell|ContentCell|

    ```

    注意：1）两侧的竖线`|`可以省略。2）第二行的每个单元格至少3个减号`---`。3）可以修改每列文字对齐方式，方法`| :--- | :---: | ---: |`。

*	**支持使用emoji表情**

*	**删除线（新增）：用两个波浪号`~~`紧密包裹文字。**

还有部分语法专门为Github平台设计的，这里就省略了。详细的GFM说明见：[https://help.github.com/categories/writing-on-github/](https://help.github.com/categories/writing-on-github/)

### 2.2.2. PHP Markdown Extra

与原生Markdown的主要不同：

*   内嵌html：块标签可以缩进不超过3个空格，且可以在块标签中选择性使用markdown语法（方法略）。

*   可以为区块元素设置**id和class属性**，实现文章内部跳转，方法略。

*   区块代码：与GFM相似，可以使用栅栏方式，在代码上下行用3个或以上波浪号`~`或反引号`` ` ``包裹，亦支持代码高亮。

*   表格：同GFM

*   支持定义列表：方法略

*   **支持脚注**：`[^1]`，在新行`[^1]: 脚注内容`   

    注意：脚注名字必须唯一

*   支持缩略语：方法略

*   强调：两字词中间的下划线不会被解释成强调。

详细的语法说明见：[https://michelf.ca/projects/php-markdown/extra/](https://michelf.ca/projects/php-markdown/extra/)   

简单中文说明：[http://b.soont.com/md/php-markdown](http://b.soont.com/md/php-markdown)

### 2.2.3. MultiMarkdown

原生markdown文档只能从纯文本转换HTML。而MultiMarkdown则是扩大了原生markdown的转换范围，让其可以方便的转换成：

*   HTML/XHTML

*   LaTeX (which can be processed into a PDF)

*   OpenDocument Text document

*   OPML   

    二次转换可以转换成更多格式，比如docx等。   

为了更好地与其他格式的兼容，MultiMarkdown借鉴很多其他的格式的语法功能

与原生语法的主要不同：

*   **支持元数据**：标题、作者、日期等信息，兼容部分YAML。

*   支持交叉引用。

*   支持添加链接和图片的属性。

*   **图片可以作为区块元素**：如果一个图片语言独立成段，会被自动解释为区块元素，图片下会添加一行图片说明。

*   支持部分**复杂表格**：兼容PHP Markdown Extra的表格，同时可以——多行表头，单元格横向合并，表格分区，表格下行表格说明等。

*   支持脚注：同PHP Markdown Extra中的脚注。

*   支持参考文献（Citations）

*   支持定义列表：同PHP Markdown Extra。

*   支持缩略语（Abbreviations）：同PHP Markdown Extra。

*   支持栅栏式区块代码：上下行3到5个反引号包裹代码，可定义语法种类，选择性语法高亮。   

    注意：首尾行的反引号数量要一致。

*   支持**MathJax公式**（区块与行内）：区块公式在新行用`\\[`和`\\]`包裹，或首尾用两个dollar`$$`包裹。行内公式用`\\(`和`\\)`包裹，或首尾各用一个dollar`$`包裹。

*   支持**上标**与**下标**：上标为单个字符，前面加`^`，为多个字符，用`^`包裹。下标为单个字符，前面加`~`，为多个字符，用`~`包裹。

*   支持术语表

*   **支持修订功能**（CriticMarkup）：可以显示修订痕迹

    *   删除：`{--删除的文本 --}`

    *   添加：`{++新增的文本 ++}`

    *   替换：`{~~删除的文本~>新增文本~~}`

    *   高亮：`{==高亮的文本==}`

    *   备注：`{>>备注文本<<}`

*   内嵌HTML，可在块级HTML中选择性地添加MultiMarkdown语法。

*   支持内嵌其他文件，txt、tet、fodt、html等

*   换行方式改为行末使用`\`换行。（原生Markdown使用2个空格换行）

*   支持**目录**：`{{TOC}}`添加目录

详细的语法说明见：[http://fletcherpenney.net](http://fletcherpenney.net/)   

这是语法快速查询表：[https://rawgit.com/fletcher/human-markdown-reference/master/index.html](https://rawgit.com/fletcher/human-markdown-reference/master/index.html)

### 2.2.4. Pandoc's Markdown

Pandoc本身是一个多格式文档的转换工具，所以Pandoc Markdown与MultiMarkdown的设计目的相似，使Markdown可以转换成更多的不同格式，因为Pandoc支持的格式很多，这也就使的Pandoc's Markdown非常的丰富，比如表格就有4种不同的书写方法。

与原生Markdown的主要不同：

*   强制换行支持两种方式：行尾两个空格换行，反斜杆换行。

*   Atx式标题之前一定要预留空行。标题行尾可加标题识别符。

*   区块引用之前一定要预留空行。

*   围栏式区块代码可以用3个以上波浪线或反引号组成的行包裹代码。之前必须留空行。

*   支持行区块

*   不同形式的列表会生成不同的列表

*   支持连续编号的范例清单，范例项目应用与整个文档，不局限与单一清单

*   支持定义列表

*   支持简单表格、多行表格、格框表格和管线表格四种表格样式

*   支持文件标题区块（类似元数据）

*   支持删除线

*   支持上标、下标

*   支持数字公式

*   支持内嵌TeX

详细的语法说明见：[http://pages.tzengyuxio.me/pandoc/](http://pandoc.org/MANUAL.html>http://pandoc.org/MANUAL.html#pandocs-markdown</a> <br>翻译的中文版：<a href=)

### 2.2.5. CommonMark

由于创始人自2004年Markdown诞生之后就没有更新过Markdown语法，众多的遗留问题没有得到解决，加上扩展语法的自由发展和Markdown编辑器的涌现，导致了很严重的方言和兼容性问题。因此有人希望对Markdown语法进行规整和统一，建立一套Markdown的语法规范，而CommonMark正是这样产物。CommonMark与一般的衍生语法不同，它的目的不是扩展Markdown的功能，而是解决原生markdown的遗留问题和方言问题，规范Markdown的书写，成为Markdown的标准。可惜此举得到Markdown创始人John Gruber的强力反对，所以至今CommonMark并没有得到广泛的认可。但是其实就CommonMark本身而言，它规范了Markdown的各项语法，有许多可取之处。CommonMark的语法说明是所有markdown语法说明中最长最详细的，优先问题、缩进问题、空行问题、嵌套问题等等容易出现语法冲突的地方都作了非常详细的说明。

与原生Markdown的主要不同：

*   定义了优先级别：区块语法的优先级别大于行内语法。

*   支持围栏式区块代码

*   支持`1）`作为有序列表的项目标记

*   支持 `\`作为换行符。

*   **列表嵌套采用行首内容对齐，而非4个空格**

*   Setext式标题支持多行

CommonMark基本没有新增内容，主要式对语法规范进行说明，对理解Markdown很有帮助，就是需要一定的Markdown基础，而且英文文档有点长，不好啃动。

详细的语法说明：[http://spec.commonmark.org/](http://spec.commonmark.org/)

 No newline at end of file

# Markdown

Markdown是我必要的写作和笔记软件，Windows下有不少优秀的编辑器，比如 Typora, Yu Writer, VNote, [Laverna](https://laverna.cc/), Smark和为知笔记等等；在线的编辑器有 [Makodo](https://www.madoko.net/editor.html)，[Penflip](https://www.penflip.com/), [看云](https://www.kancloud.cn/)等。这些编辑器都可以配合Pandoc使用，非常方便。虽然网上有不少的Markdown的教程，但是写一个自己整理的内容更加便于学习，故一些及其基本的内容省去，只需参照上述链接即可。

Markdown用反斜杠（`\`）来**转义**，表示文本中的markdown符号。在加载js的博客程序或者软件中，所有的符号都是先经过Markdown编译，之后才会进入Latex插件或者MathJax等继续编译，所以要使用一些特殊符号比如反斜杠本身也需要用反斜杠转义，也就是说要输入 `\\` 。大多数离线编辑器都已经克服了这个Markdown语法bug.

Markdown 无序列表可以用减号（`-`）放在行首作为列表标记，注意**起始行上方需要空行**。有序列表则使用任意数字加一个英文句点，编译以后出来的效果都是按顺序1,2,3排下来的。如果要在列表项目内放引用或者子列表，那么新环境需要缩进。**实际上所有的非双层引用嵌套都需要缩进。**

被尖括号`<>`包住的链接或者是邮箱可以自动变成超链接；在Pandoc中如果想要换行，但是不想分段的话，可以在行尾加上两个空格号。在Typora中只要 Shift+Space 即可.

## Madoko 注意事项

本地的Markdown编辑器的特点是加载并不比在线快，所以可以试试 MS Research 开源的 Madoko 在线 IDE 吧。Madoko 除了提供一套强大且系统的 Markdown 语法拓展之外，其输出部分也是很有意思。Madoko 的输出提供 HTML 和 PDF，其中 PDF 部分交给 LaTeX（官方默认配置是 TeXLive XeLaTeX）和 Pandoc 处理。

**CJK 处理指南.** 要优化 Madoko 的 CJK 输出其实很简单。 对于 HTML 输出，使用 html-lang 属性定义 DOM 节点即可（具体参见[知乎回答](https://www.zhihu.com/question/19637157 )）。 事实上我不需要html文件，在线预览不用如此设置，只是导出到PDF文件的时候会遇到一些问题，中文无法显示，只要在默认的标题头中加入一句 `Package:[UTF8]ctex` 即可.

### 各个Markdown编辑器的公式问题总结

大部分的 Markdown 编辑器, 尤其是在线的编辑器最大的问题是 Markdown 和 MathJax 的不完美融合, 会出现一些 Bug. 比如, 公式内的下标`_`有时候会和后续的一个`_`转变为文本强调, 有时候公式内的大括号`\{`无法显示, 公式内换行`\\` 无效等等. 下面列举我用过的编辑器的情况:

- **Madoko**: 没有什么问题, 有更多的特性, 最为强大!

- **Typora**: 基本没有 Bug, 现在在用! 

- **Yu Writer**: 另一款没有Bug的编辑器. 但目前不再更新.

- **VNote**: VNote换行符号和大括号都有bug, 需要转义; 二连续的上下标和乘号只要用空格隔开就能解决.

- **Typecho**: 最新的1.1版本的 Typecho 使用最新的  [HyperDown](https://github.com/SegmentFault/HyperDown/) 数学公式再无bug.

- **Penflip**: [Penflip](https://www.penflip.com) 的数学行内公式必须要使用`\(`，而一般我们都会使用`$`模式. 不过幸运的是，Penflip下载Markdown文件时会自动转码为美元符号。缺点是中国用户体验不佳, 比较卡.

- **看云**: ~~不支持 LaTeX!~~ 现已支持(201908), 未测试, 需要绑定手机才可使用.

## Markdown的一些可能的Bug

### 有关链接

如果是中括号需要引用的内容里使用中括号, 我们可以尽量避免[]内出现中括号, 或者使用转义. 

但是使用链接, 如果链接(或者图片)url内部有小括号(特别是结尾, 常见于维基百科链接), 如果使用转义, 打开链接时也会出现转义符, 所以网址出错. 解决方法:

> ==`%28` 代替`(`, `%29`代替`)`== 主要是后者会歧义链接部分的结束. 这是使用url符号码去代替ascii的符号. 能够解决这个问题, enjoy it!

参考文献: <http://gohom.win/2015/12/24/MD-bracket/>.