• 百 度
  • 京 东
  • 淘 宝
  • 知 乎
  • Bing
  • Google
  • Yandex
  • Quora
  • GitHub
  • StackOverflow
  • SegmentFault
  • 医 疗

Markdown(md)写作模板

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

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

方法一:使用 VScode 插件;

  1. 单击 VS Code 的扩展图标,在搜索框搜索 Markdown TOC 并安装;
  2. 将光标移至需要插入目录的位置,右键单击 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 文件的注释方式 <!--HTML 注释-->
注释的文字不会被 markdown 引擎渲染;

文章添加空行或者横线

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

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

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


如果将 border-bottom-width:1px; 数值改为 0px ,那么就变成了 空行 ;
通过调整 height:0px; 的数值,可以调整空行的高低;

文本的超链接

方法一:使用 [ ] ( ) 语法;

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

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

方法二:直接显式的显示链接;

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

语法:
花括号% 固定属性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编码实体名称 字符描述
! &#33; 惊叹号、感叹号
&#34; &quot; 双引号
# &#35; 数字标志
$ &#36; 美元标志
% &#37; 百分号
& &#38; &amp; 连字符
&#39; 单引号
( &#40; 小括号左边部分
) &#41; 小括号右边部分
* &#42; 星号
+ &#43; 加号
< &#60; &lt; 小于号
= &#61; 等于符号
- &#45; &minus; 减号
> &#62; &gt; 大于号
? &#63; 问号
@ &#64; 地址符
\ &#92; 反斜杠
[ &#91; 中括号左边部分
] &#93; 中括号右边部分
{ &#123; 大括号左边部分
} &#125; 大括号右边部分
| &#124; 竖线

更多参考链接: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 脚本;

  1. 将 451 行 ,这一步取消了对 \\,\{,\} 的转义 (escape)
    escape: /^\\([\\`*{}\[\]()# +\-.!_>])/,  
    改为 
    escape: /^\\([`*\[\]()# +\-.!_>])/,  
  2. 将459行,这一步取消了对斜体标记 _ 的转义
    em: /^\b_((?:[^_]|__)+?)_\b|^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,  
    改为 
    em:/^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,  

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

方法是使用有序列表,例如:

  1. 示例;

文字的引用

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

二级引用,引用中的引用

三级引用

文本字体颜色及背景色

颜色表示复杂一点,格式为:`$\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) 使用 &nbsp; 或者 &#160; 或者 &#xA0;
插入两个空格 (en space) 使用 &ensp; 或者 &#8194; 或者 &#x2002;
插入四个空格 (em space) 使用 &emsp; 或者 &#8195; 或者 &#x2003;
插入细空格 (thin space) 使用 &thinsp; 或者 &#8201; 或者 &#x2009;
注意:不要漏掉分号 ;

特殊符号使用 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 文档格式的规则;

注意事项:

  1. markdown 代码块中有反引号怎么办?
    可以使用更多的外层反引号包裹内存的反引号,示例如下:
    ````(四个反引号)
    ```(三个反引号)
    shell
    ```
    ````
  2. 单行代码不可以自动换行,只会出现横向滚动条进行显示;
    以下的参考文档,只是针对多行代码而言的设置,默认情况下是不需要此设置的;
    解决markdown转换后的code标签不自动换行:
    https://blog.csdn.net/tenpage/article/details/33725909
    给code标签加上如下css样式即可:
    article code { 
    white-space: normal;
    word-break: break-all;
    }
  3. 解决给高亮代码块显示行号,必须在最后一行的 三个 反引号 “ ``` ” 标点之前添加一个空行的 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='';
  4. 修正代码块 行高 与 代码行 的水平对齐 ;
    打开 /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  ;

创建有序列表和无序列表

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

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

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

  1. 使用(减号 - )创建无序列表
    - 列表一
    - 列表二
    效果如下:
  • 列表一
  • 列表二
  1. 使用(加号 + )创建无序列表,方法与上述 减号方法 相同;
  2. 使用(星号 * )创建无序列表,方法与上述 减号方法 相同;
    去除列表 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>

效果如下:

背景色

说明结束。


转载请注明来源。

文章标题:Markdown(md)写作模板

本文作者:bas369.com

发布时间:2020-03-14, 20:00:00

最后更新:2020-08-28, 23:13:30

原始链接:https://www.bas369.com/more/learning_notes/2020/03/14/Markdown%E5%86%99%E4%BD%9C%E6%A8%A1%E6%9D%BF/

版权声明: "署名-非商用-相同方式共享 4.0" 转载请保留原文链接及作者。


  • 关于我们
  • 苏公网安备 32132302010228号
  • 联系我们
目录