Markdown写作模板--博客备份

这是文章概略预览，以 more 进行分割。

@[toc]

如何为 Markdown 文件自动生成目录？

方法一：使用 VScode 插件；

单击 VS Code 的扩展图标，在搜索框搜索 Markdown TOC 并安装;
将光标移至需要插入目录的位置，右键单击 Markdown TOC: Insert/Update [^M T]，目录即自动插入；

该方法有 bug ，不好用，可以多试几个其他的 toc 插件，但是试了几个没发现有什么好用的插件；

方法二：使用 3-hexo 主题的关键词自动生成；

在使用 3-hexo 主题的情况下，
只要在文章的任意位置使用关键字 @【toc】，不区分大小写，替换中括号为英文格式；
那么文章在经过 hexo 的渲染以后，便可以在文章的相应位置显示导航目录；
效果如本文的开头所示；

解决给文章内部添加 @【toc】（不区分大小写，替换中括号为英文格式）自动生成 toc 目录的 bug；
出现 bug 为 @【toc】（不区分大小写，替换中括号为英文格式）不能出现在文章的最顶部;
出现在最顶部的时候，初次载入页面的时候，页面侧边的 toc 导航目录没有问题；
但是刷新页面以后，页面侧边的 toc 导航目录就丢失了；
该 bug 与 3-hexo 主题的 2019年09-24 更新日志 “ add: 支持文章内 toc 生成 ” 有关系；
大概的 bug 原因可能是 toc 渲染引擎的问题；
（没有找到toc函数在哪一个hexo的脚本文件中，估计应该是 \node_modules\hexo\lib\plugins\helper\toc.js 脚本文件）；
该日志在 /themes/3-hexo/layout/_partial/article.ejs 文件新增了第 75 行下面的代码调用 toc 函数：
<% post.content = post.content.replace(/@\[TOC\]/gi, "<div class='inner-toc'><h2>目录</h2>" + toc(post.content, {list_number: false}) + '</div>') %>
该 bug 的解决方法有两个：
第 1 种方法是：
如果 @【toc】添加在文章的最顶部，那么在其前面添加一个一级标题 “ # 目录 ” ；
注意：该方法不能仅仅添加一个 # 号，必须后带文字才可以；
另外，必须使用一级标题，其他等级的标题也不可以；
第 2 种方法是：
修改 /themes/3-hexo/source/js/script.js 脚本文件；
将文章内的 toc 导航目录直接复制给页面侧边栏的 toc 导航目录；
代码修改方法：打开 /themes/3-hexo/source/js/script.js 脚本文件，
将 //初始化文章toc 的代码 $(".post-toc-content").html($(".post .pjax article .toc-ref .toc").clone());
替换为下面的代码：
//原代码；
// $(".post-toc-content").html($(".post .pjax article .toc-ref .toc").clone());
//自定义代码；
if ( $( ".post .pjax article .inner-toc" ).length > 0 ) {
    $(".post-toc-content").html($($( ".post .pjax article .inner-toc" )[0]).clone());
} else {
    $(".post-toc-content").html($(".post .pjax article .toc-ref .toc").clone());
}

解决给文章内部添加 @【toc】的 bug 结束；

标题格式

最大标题一个 # 符号，标题自动换行，注意 # 号后面有空格;
最小标题六个 # 符号，标题自动换行，注意 # 号后面有空格;

字体格式

这是粗体文本，使用 ** ,直接在要换行的语句最后打上2个空格，可以实现换行，也可以直接使用 <br/> 标签
这是斜体文本，使用 * ,直接在要换行的语句最后打上2个空格，可以实现换行，也可以直接使用 <br/> 标签
~~这是删除线的错误文本~~，使用 ~~ ，直接在要换行的语句最后打上2个空格，可以实现换行，也可以直接使用 <br/> 标签；
其他的添加 删除线 方法：

<del>内容</del>
<s>内容</s>
<strike>内容</strike>
<span style="text-decoration:overline red solid"><span style="text-decoration:line-through red solid"><span style="text-decoration:underline red solid">内容</span></span></span>
下划线：text-decoration:underline;
顶划线：text-decoration:overline;
删除线：text-decoration:line-through;

文章的分类方法

Hexo不支持指定多个同级分类，下面的指定方法：

categories:   
  - Diary  
  - Life

会使分类 Life 成为 Diary 的子分类，而不是并列分类；
因此，有必要为您的文章选择尽可能准确的分类。
如果你需要为文章添加多个分类，可以尝试以下 list 的方法：

方法 1 ：  
 - [祖父类一, 父类, 孙类] 
 - [祖父类一, 父类] 
 - [祖父类二]  
**推荐使用该方法进行分类，该方法是 hexo 官方指定的方法，**| 
**且具有支持 三级 分类的优点，更多层级的分类方法未测试；**| 
代码块内字体进行 加粗体 、 斜体 的方法；
与一般方法相比，尾部多了一个 竖线 即可，但是 星号不会被隐藏；
一般来说，代码块内应该不可以进行 自定义的 字体加粗 和 斜体 设置；
猜测这应该是渲染引擎的 bug 导致的可以自定义，利用了 bug 进行的字体设置；

方法 2 ： 
 - - Diary
   - PlayStation
 - - Diary
   - Games
 - - Life
此时这篇文章同时包括了三个分类；  
PlayStation 和 Games 分别都是父分类 Diary 的子分类，  
同时 Life 是一个没有子分类的分类；
但是，该方法不支持 三级 分类，所以推荐使用 hexo 官方指定的 方法1 进行分类；

文章的注释

采用 html 文件的注释方式 
注释的文字不会被 markdown 引擎渲染；

文章添加`空行`或者`横线`

代码如下，通过参数调整可以实现空行的高低不同：

<pre style="border-top-width:0px;border-bottom-width:1px;height:0px;"></pre>

一般不添加空行，改为添加横线，用来替代空行
效果如下：

文本的超链接

方法一：使用 `[ ] ( )` 语法；

通过将链接文本包含在方括号 [ ] 内，然后将 URL 包含在括号 ( ) 内，可创建内联链接；

语法范本：本站点是使用 [GitHub Pages](https://pages.github.com/) 构建的；
示例效果：
范本：本站点是使用 GitHub Pages 构建的；
文章内页面内文章跳转内容跳转方法：[标题文字](#标题文字) ，注意，小括号里面有 # 标识标记符号。

方法二：直接显式的显示链接；

或者直接显式的显式网址链接，例如：GitHub Pages https://pages.github.com/ 构建的；

方法三：使用 Hexo 的标签插件 `Link` ；

语法：
花括号% 固定属性link 文章显式的文本链接的http网址 true或者false控制是否添加target="_blank"属性鼠标悬浮在链接上显式的文本 %花括号
示例：
这是百度的链接 花括号% link 百度网址超链接 https://www.baidu.com/ true 百度 %花括号
这是百度的链接百度网址超链接

给文本的超链接添加下划线；

方法一：使用 html 标记的标签语言 `<u>...</u>` 语法；

缺点是：下划线与文本之间的距离太小，下划线遮挡了文字底部边条；

方法二：使用 html 标记的标签语言 `<span style="">...</span>` 语法；

方法是：通过给文字添加下边框的方法，模拟下划线；
示例：<span style="display:inline-block;border-bottom:1px solid #d1e9ff;">测试显示下划线</span>
测试显示下划线

推荐取消样式表中的 display:inline-block; 设置，这样可以减小下划线与文字之间的距离；

转义字符

常用的转义字符

\\ 反斜杠
\` 反引号
\* 星号
\_ 下划线
\{\} 大括号
\[\] 中括号
\(\) 小括号
\# 井号
\+ 加号
\- 减号
\. 英文句号
\! 感叹号

Hexo 特殊符号的转义

在用 Hexo 发布博客的时候经常因为语法遇到各种问题；
例如下文的对数学公式 MathJax 的支持问题；
是因为 Hexo 取消了对部分特殊字符串和符号的转义支持；
不是在 代码块中 的特殊字符，就会被 Hexo 进行编译；
所以在非代码块中使用这些特殊字符的时候，就需要进行特别处理；
方法是使用 html 编码替换，常用的替换代码如下；

特殊字符	html编码实体编号	html编码实体名称	字符描述
!	!		惊叹号、感叹号
”	"	"	双引号
#	#		数字标志
$	$		美元标志
%	%		百分号
&	&	&	连字符
‘	'		单引号
(	(		小括号左边部分
)	)		小括号右边部分
*	*		星号
+	+		加号
<	<	<	小于号
=	=		等于符号
-	-	−	减号
>	>	>	大于号
?	?		问号
@	@		地址符
\	\		反斜杠
[	[		中括号左边部分
]	]		中括号右边部分
{	{		大括号左边部分
}	}		大括号右边部分
\|	\|		竖线

更多参考链接：https://www.cnblogs.com/polk6/p/html-entity.html

错误说明

错误提示：Template render error: (unknown path)
原因：花括号大括号 { } 导致的；

数学公式 `MathJax` 支持

修改主题的配置文件 /themes/3-hexo/_config.yml

# MathJax 数学公式支持
mathjax:
  on: true #是否启用
  per_page: false # 若只渲染单个页面，此选项设为false，页面内加入 mathjax: true

考虑到页面的加载速度，支持渲染单个页面；
设置 per_page: false ,在需要渲染的页面内加入 mathjax: true

注意：
由于 hexo 的 MarkDown 渲染器与 MathJax 有冲突；
可能会造成矩阵等使用不正常，所以在使用之前需要修改两个地方；
编辑 node_modules\marked\lib\marked.js 脚本；

将 451 行，这一步取消了对 \\,\{,\} 的转义 (escape)

escape: /^\\([\\`*{}\[\]()# +\-.!_>])/,  
改为 
escape: /^\\([`*\[\]()# +\-.!_>])/,

将459行，这一步取消了对斜体标记 _ 的转义

em: /^\b_((?:[^_]|__)+?)_\b|^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,  
改为 
em:/^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,

去除列表 `ol` 元素前面的小圆圈黑点圆点的方法

方法是使用有序列表，例如：

示例；

文字的引用

您可以使用 > 符号来实现引用文本的效果; 多层引用就使用多个 >；
一级引用

二级引用，引用中的引用

三级引用

文本字体颜色及背景色

颜色表示复杂一点，格式为：`$\color{颜色}{内容}$` ；  
以 ` $ ` 作为开头和结尾，第一个 ` { } ` 填颜色，第二个 ` { } ` 填写内容 ；  
示例如下：  
$\color{red}{talk}$ is cheap, $\color{rgba(0,255,0,.8)}{show}$ me the $\color{#ff0000}{code}$

注意：该方法不支持中文，且大括号花括号 { } 会导致 bug ，bug 解决方法参见 数学公式 MathJax 支持 段落
如果需要支持中文，建议使用更通用的 HTML 方法，markdown兼容使用 HTML 标签表示的其他文本样式;
1.Markdown 兼容 HTML，不在 Markdown 涵盖范围之内的标签，都可以直接在文档里面用 HTML 撰写，不需要额外标注；
2.一些特殊的 HTML 区块元素――比如 <div>、<table>、<pre>、<p> 等标签，必须在前后加上空行与其它内容区隔开;
还要求它们的开始标签与结尾标签不能用制表符或空格来缩进;
3.HTML 的区段（行内）标签如 <span>、<cite>、<del> 可以在 Markdown 的段落、列表或是标题里随意使用；
依照个人习惯，甚至可以不用 Markdown 格式，而直接采用 HTML 标签来格式化。

更通用的 `HTML` 方法，示例如下：
<span style="margin-left:15px; font-size:22px;color:blue;background:#00ff00;">this text is blue</span>
下划线的 `HTML` 标签方法：<u>underline</u> ；

效果如下所示：
this text is blue
下划线的 HTML 标签方法：underline ；

分割线的实现

三个或者更多的减号- ；下划线 _ ; 星号 * ; 都可以实现分割线效果；
必须单独一行，中间可含空格，示例如下：

---------- 我是妖娆的分割线 ----------

在文档中插入空格

简单说，　在 Markdown 文档中，可以直接采用 HTML 标记插入空格（blank space）；
而且无需任何其他前缀或分隔符。具体如下所示：

插入一个空格 (non-breaking space) 使用   或者   或者   ；
插入两个空格 (en space) 使用 &ensp; 或者   或者   ；
插入四个空格 (em space) 使用 &emsp; 或者   或者   ；
插入细空格 (thin space) 使用   或者   或者   ；
注意：不要漏掉分号 ; 。

特殊符号使用 HTML 编码的方式

特殊符号的表示方法：
© — ¨ — ™ — ¡ — £ — & — < — > — ¥ — €
® — ± — ¶ — § — ¦ — ¯ — « — ·
数学运算符号的表示方法：
X² — Y³ — ¾ — ¼ — × — ÷ — »
摄氏温度的表示方法：
18ºC
上标的 HTML 标签方法：
2^10^ ；
下标的 HTML 标签方法：
H2O ；

代码引用使用反引号

使用单 反引号 可标注句子中的代码或命令，反引号中的文本不会被格式化；
例如使用 git status 列出尚未提交的所有新文件或已修改文件;

如果需要在反引号内使用 空格缩进 ，那么将其直接转换为 三个反引号 标注的代码块显示即可；
代码块应该是可以理解为反引号的加强版；代码块可以不注明语言类别；
不需要注明语言，默认的语言规则是 linux 编译程序使用的 makefile 文档格式的规则
如果你需要为文章添加多个分类，可以尝试以下 list 的方法：
代码块内包含空格缩进的示例：
  - - Diary
    - PlayStation
  - - Diary
    - Games
  - - Life

表情符号 Emoji 😄 的使用

如果你想在 md 中使用 emoji 表情的话，需要另外下载相关插件；
比如 markdown-it-emoji 或者其他的类似插件；
通过键入:表情代码: 可在您的写作中添加表情符号；
例如：:+1: 显示 :+1: ， :smile: 显示 :smile: ；

有关可用表情符号和代码的完整列表：
请查看 emoji-cheat-sheet.com

文章注脚说明

这是一个链接到谷歌的[^脚注]。
[^脚注]: http://www.google.com

注意：脚注必须换行另起一行，否则无效；
脚注链接在渲染后，会自动被搬运到最后面，请到文章末尾查看；
并且文字后面的脚注文本在渲染后，可以直接跳转到页面底部加注链接的地方。
该方法在 3-hexo主题下无效，原因不明；
官方的说明：
用markdown语法写完文章推送到服务器, [^1]脚注不能用：
https://hexo.io/zh-cn/docs/tag-plugins
github用的markdown很多语法都是不支持的；
这和 markdown 引擎有关，如果一定要脚注得换个 markdown 渲染引擎；
本主题实际未更换渲染引擎，以下更换渲染引擎方法仅供参考；
卸载默认引擎：npm uninstall hexo-renderer-marked –save
安装新的引擎：npm install markdown-it –save

代码块语法高亮

要将代码或文本格式化为各自的不同行，请使用三个连续的反引号 ``` ；
例如，一些基本的 Git 命令为：

```
git status
git add
git commit
```

您可以添加可选的语言标识符，以在围栏代码块中启用语法突显；
例如，要语法突显 Ruby 代码：

```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

可以不注明语言类别，那么默认的语言规则是 linux 编译程序使用的 makefile 文档格式的规则；

注意事项：
markdown 代码块中有反引号怎么办？
可以使用更多的外层反引号包裹内存的反引号，示例如下：
````（四个反引号）
```（三个反引号）
shell
```
````
单行代码不可以自动换行，只会出现横向滚动条进行显示；
以下的参考文档，只是针对多行代码而言的设置，默认情况下是不需要此设置的；
解决markdown转换后的code标签不自动换行：
https://blog.csdn.net/tenpage/article/details/33725909
给code标签加上如下css样式即可：
article code { 
white-space: normal;
word-break: break-all;
}
解决给高亮代码块显示行号，必须在最后一行的三个反引号 “ ``` ” 标点之前添加一个空行的 bug ；
// 打开 /themes/3-hexo/layout/_partial/footer.ejs  文件，找到 第 37 行 下面的代码：
var lines = $(this).text().split('\n').length - 1, widther='';
// 取消  “  - 1  ”  的设置，将其改为下面的代码：
var lines = $(this).text().split('\n').length, widther='';
修正代码块行高与代码行的水平对齐；
打开 /themes/3-hexo/source/css/_partial/post.styl  样式表文件；
------ 参考模板 footer.ejs 第 357 行 .pre-numbering{ ，以及  第 56 行 /*代码高亮，行号对齐*/ ；
------ 使用 em 单位，子元素字体大小的em是相对于父元素字体大小；  
------ 元素的width/height/padding/margin用 em 的话是相对于该元素的 font-size ；
------ 找到 第 247 行的   font-size 15px   样式；将其值修改为   16px  ； 
------ 控制代码 code 字体的大小，影响代码边框的大小；
------ 找到 第 179 行的   line-height 30px   样式；将其值修改为  line-height 1.6  ；  
------ 修改文章内部引用的行高，修为为保持与 顶部 第 1 行的  .post  设置相同；
------ 后来统一改为 1.875 ；
------ 修改高亮代码行的行号宽度，在 /themes/3-hexo/layout/_partial/footer.ejs 文件；
------ 找到 第 357行的 .pre-numbering{ 样式；  
------ 找到 padding: 0.5em 3px 0.7em 5px;  将其  0.7em  修改为 0.5em  ；

创建有序列表和无序列表

所谓的无序列表，就是前面没有序号的列表；
所谓的有序列表，就是列表前面包含了序号；

创建的无序列表三种方法，即使用 `- ， + ， *` 三种符号中的任意一种：

注意： - + * 跟内容之间都要有一个空格；

使用（减号 - ）创建无序列表
- 列表一
- 列表二
效果如下：

列表一

列表二

使用（加号 + ）创建无序列表，方法与上述减号方法相同；

使用（星号 * ）创建无序列表，方法与上述减号方法相同；
去除列表 ol 元素前面的小圆圈黑点圆点的方法是使用有序列表。

无序列表嵌套

嵌套列表：通过在一个列表项下面 缩进 一个或多个其他列表项，可创建嵌套列表；
在嵌套列表项的前面键入空格字符；
直至列表标记字符 - ， + ， * 位于其上方条目中第一个文本字符的正下方。
范本格式如下：
+ 列表一   
+ 列表二  
  + 列表二-1  
  + 列表二-2  
+ 列表三  
  * 列表一  
  * 列表二  

创建有序列表使用数字加点号 `.` 标识，例如：`1.`

对列表排序，在每行前面添加一个编号;
1.列表内容
2.列表内容
3.列表内容
注意：序号跟内容之间空格可以有，也可以没有；

列表注意事项

如果在单一列表项中包含了多个段落，为了保证渲染正常，`*` 与段落首字母之间必须保留四个空格；  
*    段落一  
     小段一  
另外，如果在列表中加入了 区块引用 或 二级标题，在标记符前也需要缩进 4 个空格；  
* 段落一  
    > 区块标记一  
    * 内嵌段落一  
注：
记住一个原则，` 引用 ` 和 ` 段落 ` 如果在和 ` 列表 ` 配合使用的时候出现了问题，就缩进一次；  
四个空格或者一个制表符代表一次缩进；如果一次缩进没有解决问题，那就两次；  
创建 ` 多层级嵌套列表 ` 使用的应该是相同的方法；  
例如：
在第一个嵌套列表项中，嵌套列表项内容第一个嵌套列表项之前有七个空格；  
那么就需要将第二个嵌套列表项 也一样的 缩进七个空格。

任务列表

要创建任务列表，在列表项目前面加一个常规 空格 字符，然后接上中括号 [ ] ;
要将任务标记为已完成，中括号中填上英文小写字母 x ，即使用 [x] ；
以下为无序列表配合任务列表的写法示例：

- [x] GFM task list 1
- [x] GFM task list 2
- [ ] GFM task list 3
    - [ ] GFM task list 3-1
    - [ ] GFM task list 3-2
    - [ ] GFM task list 3-3
- [ ] GFM task list 4
    - [ ] GFM task list 4-1
    - [ ] GFM task list 4-2

效果如下所示：

GFM task list 1
GFM task list 2
GFM task list 3
- GFM task list 3-1
- GFM task list 3-2
- GFM task list 3-3
GFM task list 4
- GFM task list 4-1
- GFM task list 4-2
  
  在 to do 事项前面添加复选框的方法：
  即想在 hexo 下使用 markdown 语法写文章时，使用 [ ] 、 [x] ；
  实现 Github 上特有的 markdown 方言（Github Flavored Markdown, GFM）来输出 checkbox ；
  卸载默认引擎：npm uninstall hexo-renderer-marked –save
  安装新的引擎：npm install markdown-it –save
  安装新引擎插件：npm install markdown-it-checkbox –save
  本主题默认实现了复选框功能，不需要上述的额外操作；

绘制表格

空一行：表格的前面必须空一行，否则会渲染不出表格;

书写格式如下：
空一行
| 项目        | 价格   |  数量  |
| --------   | -----:  | :----:  |
| 计算机      | $1600   |   5     |
| 手机        |   $12   |   12   |
| 管线        |    $1    |  234  |

效果如下：

项目	价格	数量
计算机	$1600	5
手机	$12	12
管线	$1	234

注：中间 - 有一个即可，为了对齐用不少于三个；
连接线 - 默认不加冒号 : 是左对齐，两边都加是居中，右边加是右对齐;
即设定内容居中、居左、居右的方法如下：
使用 :---------: 居中；
使用 :---------- 居左；
使用 ----------: 居右；
Hexo 默认引擎不支持上述的居中、居右、居左的方法；
Hexo 默认引擎只有默认居左的方法；
解决方案参见：https://github.com/hexojs/hexo/issues/3657
方法一：配置 gfm ，https://github.com/hexojs/hexo-renderer-marked#options
方法二：替换 markdown 渲染引擎为 markdown-it ，参见上文的 “ 文章注脚说明 ”
方法三：使用 html 标签语言，可以设置居左、居中、居右、字体、颜色、大小等待；
使用的标题可以使用 a 、 p 、 span 等标签包裹文字；
参考链接：https://www.zhihu.com/question/21160553
表格的前面必须空一行，否则会渲染不出表格;
表格原生的语法两边都要用竖线 | 包起来;
在表格中，不可以按正常行文的方式，可以用 <br/>标签实现换行；
上述表格如果在导出为 html 时边框会消失，这种情况直接修改 html 代码即可，修改方法如下：
<table border="1" cellspacing="0">
</table>
表格的背景色设置方法：
<form><table><tr><td bgcolor=yellow>背景色</td></tr></table></form>
效果如下：

背景色