Markdown

Markdown

MarkDown用法/注意事項備忘

本文用於記錄Markdown的編寫規範與心得，包含vscode相關的配置。原文是用markdown格式寫的，稍微改了下發了博客，格式可能會很奇怪。。

 

Markdown是一種輕量級的標記語言。
標記語言(Markup Language)是一種將文本以及文本相關的其餘信息結合起來，展示出關於文檔結構和數據處理細節的計算機文字編碼，HTML(HyperText Markup Language)、XML(Extensible Markup Language)也屬於標記語言。

用Markdown，能夠花相對較低的成本寫出有着豐富內容與結構的文本。而且配合編輯器的支持，不須要渲染，其 源碼 自己就具備很是高的可讀性與可寫性。而造成、遵照規範能夠進一步提升讀寫效率。

Markdown的基本語法可參考Github的Mastering Markdown

Markdown的規範以VSCode的插件markdownlint的markdownlint 與Markdown Style Guide爲準，並將根據渲染視圖的變化來判斷規則是否有效。

本文默認使用VSCode，至少須要如下插件：Markdown All in One, markdownlint，可選如下插件：

插件名	做用	備註
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

1. 在父子無序列表中，子無序列表須要縮進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,
}