hexo[Matery] 玩转 Markdown

最近想起之前遇到的一个残留的 BUG 问题，是关于 hexo-renderer-markdown-it 插件的。

我在 ISSUE 上看到这个问题也有不少人遇到过，但是都没有给出具体的解决方案。

于是，我捣鼓了一下 hexo-renderer-markdown-it 插件，不仅解决了这个问题，还做了一些关于这个插件的优化和曾强及补充。

下面是记录具体修改及配置的方法，大家可以按需求自己跳转目录。

一、安装 Markdown 渲染器

1. 用管理员身份打开 Git Bash，然后依次执行以下代码：

$ cd {hexo-blog}.github.io/ # 首先进入你的 hexo 的根目录
$ npm un hexo-renderer-marked --save # 卸载 hexo 默认的 markdown 渲染引擎
$ npm i hexo-renderer-markdown-it --save # 安装 markdown-it

2. 打开根目录下的 _config.yml 文件，添加如下配置信息（记得把原来的 markdown 渲染器的配置信息注释掉或者删除）：

# md渲染
markdown:
    preset: 'default'
    render:
    html: true
    xhtmlOut: false
    langPrefix: 'language-'
    breaks: true
    linkify: true
    typographer: true
    quotes: '“”‘’'
    enable_rules:
    disable_rules:
    plugins:
    anchors:
    level: 2
    collisionSuffix: ''
    permalink: false
    permalinkClass: 'header-anchor'
    permalinkSide: 'left'
    permalinkSymbol: '¶'
    case: 0
    separator: '-'

3. 重新生成静态文件，刷新配置信息使其生效：

$ hexo cl && hexo g

二、修复章目录锚点失效

1. 用管理员身份打开 Git Bash，然后依次执行以下命令：

$ cd {hexo-blog}.github.io/ # 首先进入你的 hexo 的根目录
$ npm i markdown-it-named-headings --save # 安装相关插件

2. 然后来到根目录下的 _config.yml 文件，在 hexo-renderer-markdown-it 插件的配置信息中找到 plugins 项，修改如下：

markdown:
    plugins:
    - markdown-it-named-headings

3. 重新生成静态文件，刷新配置信息使其生效：

$ hexo cl && hexo g

三、添加 MD 脚注解析

博主目前用的是 hexo-renderer-markdown-it 6.0.1，该本本中已经集成了 markdown-it-footnote 插件

1. 如果你的 hexo-renderer-markdown-it 插件不包含 markdown-it-footnote 插件（在其 package.json 文件^[1]中查看依赖），请自己安装该插件（如果自带有，请直接跳第二部）：

$ npm i markdown-it-footnote --save

2. 然后来到根目录下的 _config.yml 文件，在 hexo-renderer-markdown-it 插件的配置信息中找到 plugins 项，修改如下：

markdown:
    plugins:
    - markdown-it-footnote

3. 重新生成静态文件，刷新配置信息使其生效：

$ hexo cl && hexo g

3.1 使用方法

引自 Markdown 官方教程 - Markdown 脚注。

脚注使您可以添加注释和参考，而不会使文档正文混乱。当您创建脚注时，带有脚注的上标数字会出现在您添加脚注参考的位置。读者可以单击链接以跳至页面底部的脚注内容。

要创建脚注参考，请在方括号（[^1]）内添加插入符号和标识符。标识符可以是数字或单词，但不能包含空格或制表符。标识符仅将脚注参考与脚注本身相关联-在输出中，脚注按顺序编号。

在括号内使用另一个插入符号和数字添加脚注，并用冒号和文本（[^1]: My footnote.）。您不必在文档末尾添加脚注。您可以将它们放在除列表，块引号和表之类的其他元素之外的任何位置。

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you like.

呈现的输出如下所示：

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

Indent paragraphs to include them in the footnote.

`{ my code }`

Add as many paragraphs as you like.

3.2 优化增强

该段内容只针对 Matery 主题，其他主题可能有所不同，仅作为参考

这个脚注是通过 <a> 标签实现的，而在 Matery 主题下，默认所有 <a> 标签都会被添加上 target="_blank" 属性。所有，一点这个脚注就会打开一个新标签页，而不是像目录一样在页面内跳转。

所以，我们需对主题的源代码做一些魔改，使其既满足脚标页内跳转，又不影响原来的 <a> 标签新标签页打开。

1. 首先打开主题目录下的 source/js/ 文件夹，打开 matery.js 文件。
2. Ctrl + F 搜索 #articleContent a。
3. 找到 $('#articleContent a').attr('target', '_blank'); 代码，在其后面添加如下代码：

$('#articleContent .footnote-ref a').attr('target', '_self');
$('#articleContent a.footnote-backref').attr('target', '_self');

4. 最后重新部署以下即可。

四、添加 MD 任务列表

1. 用管理员身份打开 Git Bash，然后依次执行以下命令：

$ cd {hexo-blog}.github.io/ # 首先进入你的 hexo 的根目录
$ npm i markdown-it-checkbox --save # 安装相关插件

2. 然后来到根目录下的 _config.yml 文件，在 hexo-renderer-markdown-it 插件的配置信息中找到 plugins 项，修改如下：

markdown:
    plugins:
    - markdown-it-checkbox

3. 重新生成静态文件，刷新配置信息使其生效：

$ hexo cl && hexo g

4.1 使用方法

引自 Markdown 官方教程 - Markdown 任务列表语法。

任务列表使您可以创建带有复选框的项目列表。在支持任务列表的Markdown应用程序中，复选框将显示在内容旁边。要创建任务列表，请在任务列表项之前添加破折号-和方括号[ ]，并在[ ]前面加上空格。要选择一个复选框，请在方括号[x]之间添加 x 。

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

呈现的输出如下所示：

4.2 修复 Matery 中不显示 BUG

在 Matery 主题下，可能会出现任务列表无法显示的情况。

我尝试调试来查找问题的来源，最后在 materialize.min.css 文件中找到了相关问题代码：

咋也不知道作者当初为什么这么定义，也不能（强烈不建议直接改源码）随随便便就改人家的源码，万一改了之后在其他某个地方多了某个 BUG，我们甚至都不知道。

庆幸闪狐大佬为我们提供了 my.css 文件，用于定义自己的 css 代码。

1. 打开主题目录下中 /source/css/ 文件中的 my.css 文件。
2. 然后添加如下代码：

/* <input type="checkbox"> 不显示 bug 修复 */
#articleContent input[type="checkbox"]:not(:checked), 
#articleContent input[type="checkbox"]:checked {
    opacity: 1;
    pointer-events: auto;
}

五、添加 MD 上标和下标

博主目前用的是 hexo-renderer-markdown-it 6.0.1，该本本中已经集成了 markdown-it-sub 和 markdown-it-sup 插件

1. 如果你的 hexo-renderer-markdown-it 插件不包含 markdown-it-sub 和 markdown-it-sup 插件（在其 package.json 文件^[1:1]中查看依赖），请自己安装该插件（如果自带有，请直接跳第二部）：

$ npm i markdown-it-sub markdown-it-sup --save

2. 然后来到根目录下的 _config.yml 文件，在 hexo-renderer-markdown-it 插件的配置信息中找到 plugins 项，修改如下：

markdown:
    plugins:
    - markdown-it-sub
    - markdown-it-sup

3. 重新生成静态文件，刷新配置信息使其生效：

$ hexo cl && hexo g

5.1 使用方法

LaTex 形式
$LaTex^上标$
$LaTex_下标$

Html 形式
Html<sup>上标</sup>
Html<sub>下标</sub>

Markdown 形式
Markdown^上标^
Markdown~下标~ 

5.2 修复上下标同时出现时无法左对齐

暂未找到解决方案…

六、添加 MD 图片大小指定

1. 用管理员身份打开 Git Bash，然后依次执行以下命令：

$ cd {hexo-blog}.github.io/ # 首先进入你的 hexo 的根目录
$ npm i markdown-it-imsize --save # 安装相关插件

2. 然后来到根目录下的 _config.yml 文件，在 hexo-renderer-markdown-it 插件的配置信息中找到 plugins 项，修改如下：

markdown:
    plugins:
    - markdown-it-imsize

3. 重新生成静态文件，刷新配置信息使其生效：

$ hexo cl && hexo g

6.1 基本使用

官方提供语法标准
![](./Demo.gif =100x100)

6.2 进阶使用

其实，按照官方提供的语法已经基本够用。但实际上，在官方语法中真正起作用的往往是图片宽度的指定。
所以，经过尝试我选择以下几种写法来提高效率。

只指定宽度
![](./Demo.png =100x) # 按照像素宽度指定图片大小，保持图片比例
![](./Demo.jpg =50%x) # 按照百分比指定图片大小，保持图片比例

七、添加 MD 高亮标记

博主目前用的是 hexo-renderer-markdown-it 6.0.1，该本本中已经集成了 markdown-it-mark 插件

1. 如果你的 hexo-renderer-markdown-it 插件不包含 markdown-it-mark 插件（在其 package.json 文件^[1:2]中查看依赖），请自己安装该插件（如果自带有，请直接跳第二部）：

$ npm i markdown-it-mark --save

2. 然后来到根目录下的 _config.yml 文件，在 hexo-renderer-markdown-it 插件的配置信息中找到 plugins 项，修改如下：

markdown:
    plugins:
    - markdown-it-mark

3. 重新生成静态文件，刷新配置信息使其生效：

$ hexo cl && hexo g

7.1 使用方法

==需要<Mark>标记的文字==

7.2 样式修改

1. 打开根目录的 /source/css/ 文件夹里的 matery.css 文件。
2. Crtl + F 搜索 “mark”，大约在 218 行有如下代码：

mark {
    background-color: #fcf8e3;
    padding: .2em
}

3. 修改其 CSS 样式就行了。大家也可以参考我的样式：

mark {
    background-color: #fff143; // 中国传统颜色——鹅黄
    padding: .2em;
    border-radius: 5px;
}

八、添加 MD 文字下划线

博主目前用的是 hexo-renderer-markdown-it 6.0.1，该本本中已经集成了 markdown-it-ins 插件

1. 如果你的 hexo-renderer-markdown-it 插件不包含 markdown-it-ins 插件（在其 package.json 文件^[1:3]中查看依赖），请自己安装该插件（如果自带有，请直接跳第二部）：

$ npm i markdown-it-ins --save

2. 然后来到根目录下的 _config.yml 文件，在 hexo-renderer-markdown-it 插件的配置信息中找到 plugins 项，修改如下：

markdown:
    plugins:
    - markdown-it-ins

3. 重新生成静态文件，刷新配置信息使其生效：

$ hexo cl && hexo g

8.1 使用方法

++你需要插入的文字++

详情请参考 W3school 的 标签。

九、添加 MD 缩写注释

博主目前用的是 hexo-renderer-markdown-it 6.0.1，该本本中已经集成了 markdown-it-abbr 插件

1. 如果你的 hexo-renderer-markdown-it 插件不包含 markdown-it-abbr 插件（在其 package.json 文件^[1:4]中查看依赖），请自己安装该插件（如果自带有，请直接跳第二部）：

$ npm i markdown-it-abbr --save

2. 然后来到根目录下的 _config.yml 文件，在 hexo-renderer-markdown-it 插件的配置信息中找到 plugins 项，修改如下：

markdown:
    plugins:
    - markdown-it-abbr

3. 重新生成静态文件，刷新配置信息使其生效：

$ hexo cl && hexo g

9.1 使用方法

Markdown 中的语法
*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium
The HTML specification is maintained by the W3C.

解析成的 Html 语法
<p>
    The 
    <abbr title="Hyper Text Markup Language">HTML</abbr> 
    specification is maintained by the 
    <abbr title="World Wide Web Consortium">W3C</abbr>
    .
</p>

实际效果：

提示：在某些浏览器中，当您把鼠标移至带有 标签的缩写词/首字母缩略词上时， 标签的 title 属性可被用来展示缩写词/首字母缩略词的完整版本。

十、添加 MD 定义列表

博主目前用的是 hexo-renderer-markdown-it 6.0.1，该本本中已经集成了 markdown-it-deflist 插件

1. 如果你的 hexo-renderer-markdown-it 插件不包含 markdown-it-deflist 插件（在其 package.json 文件^[1:5]中查看依赖），请自己安装该插件（如果自带有，请直接跳第二部）：

$ npm i markdown-it-deflist --save

2. 然后来到根目录下的 _config.yml 文件，在 hexo-renderer-markdown-it 插件的配置信息中找到 plugins 项，修改如下：

markdown:
    plugins:
    - markdown-it-deflist

3. 重新生成静态文件，刷新配置信息使其生效：

$ hexo cl && hexo g

10.1 使用方法

引自 Markdown 官方教程 - Markdown 定义列表。

一些Markdown处理器允许您创建术语及其对应定义的定义列表。要创建定义列表，请在第一行上键入术语。在下一行，键入一个冒号，后跟一个空格和定义。

First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.

HTML看起来像这样：

<dl>
  <dt>First Term</dt>
  <dd>This is the definition of the first term.</dd>
  <dt>Second Term</dt>
  <dd>This is one definition of the second term. </dd>
  <dd>This is another definition of the second term.</dd>
</dl>

呈现的输出如下所示：

10.2 修复 Matery 无样式问题

虽然 hexo-renderer-markdown-it 插件解析成功了，但是在 Matery 主题下好像并未对该标签进行样式定义。所以，这需要我们自己定义其样式：

所以，我自己定义了一个样式，如果喜欢可以直接拿去用：

/* MD 定义列表样式定义 */
#articleContent dl {
    padding: 20px 0;
    font-size: 1.2em;
    line-height: 1.2em;
}
#articleContent dt {
    margin: 1em 0 0.2em 0;
    font-family: fantasy;
}
#articleContent dd {
    margin-left: 2em;
    font-family: emoji;
    font-weight: bold;
}

效果如图：

十一、附录

11.1 Markdown 基础语法

元素	Markdown 语法
标题	# H1 ## H2 ### H3 ...
粗体	**bold text**
斜体	*italicized text*
引用块	> blockquote
有序列表	1. First item 2. Second item 3. Third item
无序列表	- First item - Second item - Third item
代码	ˋcodeˋ
分隔线	---
链接	[title](https://www.example.com)
图片	

11.2 Markdown 进阶语法

元素	Markdown 语法
表格	| Syntax | Description | | ----------- | ----------- | | Header | Title | | Paragraph | Text |
代码块	ˋˋˋ { "firstName": "John", "lastName": "Smith", "age": 25 } ˋˋˋ
脚注	Here's a sentence with a footnote. [^1] [^1]: This is the footnote.
标题编号	### My Great Heading {‏#custom-id‏}
定义列表	term : definition
删除线	~~The world is flat.~~
任务列表	- [‏x] Write the press release - [‏ ] Update the website - [‏ ] Contact the media

11.3 Markdown 高级语法

元素	Markdown 语法
上标	^上标^
下标	~下标~
指定大小的图片	 
高亮标记	==Mark Text==
插入字（下划线）	++Ins Text++
缩写注释(abbr)	*[Abbr]: Abbreviation

---

1. 在根目录的 /node_modules/hexo-renderer-markdown-it/ 文件夹里. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎