Markdown

Markdown

MarkDown用法/注意事项备忘

本文用于记录Markdown的编写规范与心得,包含vscode相关的配置。原文是用markdown格式写的,稍微改了下发了博客,格式可能会很奇怪。。

Markdown是一种轻量级的标记语言。
标记语言(Markup Language)是一种将文本以及文本相关的其他信息结合起来,展现出关于文档结构和数据处理细节的计算机文字编码,HTML(HyperText Markup Language)、XML(Extensible Markup Language)也属于标记语言。

用Markdown,可以花相对较低的成本写出有着丰富内容与结构的文本。并且配合编辑器的支持,不需要渲染,其 源码 本身就具有非常高的可读性与可写性。而形成、遵守规范可以进一步提高读写效率。

Markdown的基本语法可参考Github的Mastering Markdown

Markdown的规范以VSCode的插件markdownlintmarkdownlint 与Markdown Style Guide为准,并将根据渲染视图的变化来判断规则是否有效。

本文默认使用VSCode,至少需要以下插件:Markdown All in Onemarkdownlint,可选以下插件:

插件名作用备注
Markdown Preview Github Styling将Makrdown的预览改为Github的样式 
Markdown Preview Mermaid Support添加mermaid图表的支持,用法为```(mermaid) 
Markdown Checkbox扩展Markdown中checkbox的功能,支持用快捷键一键勾选,列出所有checkbox并快速勾选 

杂项

  1. 空格可用 替代
  2. 超链接中,可用-表示Markdown标题 # 后接的空格
  3. ---轻量地切割文本

粗体、斜体

粗体表强调,斜体表引用或次级的强调

粗体 用 **blod**
斜体 用 _italic_

标题

标题(heading)是markdown非常重要的结构,用于对文本进行层次结构的划分。

配置使用重复标题

根据MarkdownLint的MD24,默认不能有重复的标题,但可以通过修改配置文件来修改该约束,配置文件修改内容如下:

 
"markdownlint.config": {
    "default": true,
    "MD024": {
        "siblings_only": true
    }
}
 

MarkdownLint 对于限制重复标题,给出的原因是:如果标题重复,某些解析Markdown生成的锚(anchor)可能会出现问题。但目前使用的Markdown All in One生成的目录没有这个问题。

列表

  • 列表中,任意行的子列只能 全是有序 或 全是无序
  • 子非列表内容统一缩进到父列的内容的起始位置(原因见该节下文)
  • 可通过用注释子列的方式实现具体到列的提示
  • 在不需要明确优先级的时候,优先使用无序列表

关于第2点的解释:

1. a
   - b1
   1. c
   - b2

上述文本b1, b2, c看起来是并列关系,然而vscode实际渲染出来的是递进关系,c是b1的子列


目前发现,VSCode的Markdown插件的自动缩进/缩进校验的规则为:子列缩进到与父列的内容并列,如:

1. a
   - f
...
11. b
    - be care!!!

- [ ] checkbox1
  - [ ] sub_checkbox checkbox的内容从方括号开始

  

有序列表
子有序列表缩进的空格数没有(没看到有)限制,不过 Markdown ALl In One 1.8 更新后,自动缩进由4个变为3个空格。
无序列表
MD007 - Unordered list indentation

在父子无序列表中,子无序列表需要缩进2个空格

有序 + 无序列表的缩进
MD007 只规定了无序父子列表之间必须缩进2个空格,没有对其他情况的缩进进行限制
目前我先自己定下规范,对于非无序父子列表间的缩进,一律以Markdown ALl In One的自动缩进规则:子列缩进到与父列的内容并列 进行处理
注释
注释也是可以有分层结构,如下:
> f1
>> ff2
>> ff2
>>> ff3

  
数学符号
依靠VSCode插件MarkDown+Math实现,Markdown All in One即提供了该支持,可用右斜杠\唤起特殊符号的自动补全,另起一行的写法形如:
$$ 2^2 + 3^2 + \Sigma _u^o $$

行内写法 $2^2$

 渲染图: 
 
具体函数参见 https://katex.org/docs/supported.html

遗憾的是源代码中的显示效果并不好

表格
尽量不要自动格式化表格。目前的Markdown All in One插件就有附带这个功能,但自动格式化表格实际就是用空格与-撑起表格,当表格中的文本过长而需要换行时,会造成难以阅读的反效果。并且由于空格或-字符的宽度与中文字体不同,包含中文时自动格式化会不整齐。
手动添加的表格,目前采用如下的写法:
Ha | Hb | Hc
-|-|-
as | bs
as | - | cs
|
as |

 渲染图:



图表
Mermaid
需要 Markdown Preview Mermaid Support 插件,mermaid是一种类似于Markdown的将标记文本转化为图表的JS工具,支持几种图表,可见 官网。由于相对其他图表的文本相对复杂,目前仅考虑使用流程图。
使用方式如下:
1. 纵向流程图:

        ```mermaid
        graph TD;
            a-->b
            b-- 导致了 -->c
            c---d
            d[多文字单元格]---e
        ```

   2. 横向流程图

        ```mermaid
        graph LR;
            a-->b
        ``` 
 渲染图:




内容过多的处理
目前看来,Markdown并不适合篇幅过长的文档:

VS Code 目录、大纲功能过于简陋
文档过大时编辑会卡顿
有序列表长度超过10时(序号字符长度大于1),可能会出现奇怪的问题(如退格异常)

因此:

当Markdown文档过大时,需要考虑进行拆分。拆分的最好是从功能模块结构上进行拆分,既减小了文档容量,又通过细化结构优化了可读性
优先使用无序列表

 
checkbox
在使用Markdown Checkbox 插件扩展checkbox功能前,需要额外配置:

{
    "markdown-checkbox.typeOfBulletPoint": "-",
    "markdown-checkbox.checkmark": "x"
}

  

插件提供了Ctrl + Shift + Enter来标记完成。可在 VS Code 的右下角列出整个文档的checkbox,但遗憾的是只能进行checkbox的批量选中,无法直接跳转到checkbox的位置(往往选中前需要备注下处理方式等其他信息)。

配置自动换行
markdown默认的自动换行(editor.wordWrap": "on")会导致最后有几个字没有换行,需要将换行模式设为bounded,再将换行阈值设为尽量大。
vscode通用的配置对markdown无效,需要针对语言进行专门的配置:

"[markdown]": {
    "editor.wordWrap": "bounded",
    "editor.wordWrapColumn": 200,
}

相关推荐