L
O
A
D
I
N
G

hexo[Matery] 玩转 Markdown


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

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


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

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

一、安装 hexo-renderer-markdown-it

  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

二、修复 markdown-it 中文章目录 TOC 锚点失效

  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
  1. 然后来到根目录下的 _config.yml 文件,在 hexo-renderer-markdown-it 插件的配置信息中找到 plugins 项,修改如下:

    markdown:
      plugins:
        - markdown-it-footnote
  2. 重新生成静态文件,刷新配置信息使其生效:

    $ hexo cl && hexo g

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.

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

1)使用方法

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

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

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

呈现的输出如下所示:

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-submarkdown-it-sup 插件

  1. 如果你的 hexo-renderer-markdown-it 插件不包含 markdown-it-submarkdown-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

1)使用方法

LaTex 形式
$LaTex^上标$ $LaTex_下标$
Html 形式
Html<sup>上标</sup> Html<sub>下标</sub>
Markdown 形式
Markdown^上标^ Markdown~下标~

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

1)基本使用

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

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

1)使用方法

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

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

使用方法

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

详情请参考 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

使用方法

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

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>

呈现的输出如下所示

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;
}

效果如图:

附录

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)
图片![alt text](image.jpg)

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

3)Markdown 高级语法

元素Markdown 语法
上标^上标^
下标~下标~
指定大小的图片![alt text](image.jpg =100x100)
![alt text](image.jpg =50%x)
高亮标记==Mark Text==
插入字(下划线)++Ins Text++
缩写注释(abbr)*[Abbr]: Abbreviation

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


文章作者: SeaYJ
版权声明: 本博客所有文章除特別声明外,均采用 CC BY-NC-ND 4.0 许可协议。转载请注明来源 SeaYJ !
评论
  目录