markdown學習筆記（個人向） Part.1

1. 推薦插件

markdown：
- 安裝支持markdown的插件；
markdown-preview-github-styles：
- 可以將VS Code上默認的markdown預覽樣式修改成github上常用的形式，很大程度上提高文件的可讀性；
vscode-wordcount-cjk：
- 用于統計markdown文檔的字數；
markdown-preview-enhanced：
- 最常用的markdown插件，內置了非常多的其他插件；
- 支持功能眾多：
  1. 外部文件導入；
  2. 支持html，pdf，word等格式文檔導出；
  3. 可以使用html語言和自定義css；
  4. 可以快速拷貝上傳圖片；
  5. 可以使用Mermaid，PlantUML，gnuplet等外部圖像工具；
markdownlint:
- 對編寫markdown文檔進行格式檢查，并給出相應的提示；
- 對于養成嚴格的編寫習慣有幫助；
markdown-index：
- 等同于 markdown add index 命令，給段落標題批量添加編號;
auto close tag:
- 編寫html時自動填充關閉標簽，對于在markdown中調用其他html標簽或者設置字段的自定義格式有幫助；
markdown-all-in-one:
- 上述markdown-preview-enhanced的下位替代，提供了很多的功能：
  1. 列表的自動化處理；
  2. 提供數學公式的支持；
  3. 提供鍵盤快捷鍵的支持；
Pangu-Markdown：
- 自動為 Markdown 文件的中英文之間添加空格，中英文符號轉換等；
markdown emoji：
- 快速插入markdown表情；

2. 基本語法

事實上，markdown是一種被包裝的html文件，在markdown中可以直接使用html編寫你需要的內容，也可以使用markdown語法編寫對應的組件簡化操作，如：標題 = # 標題；

2.1 預設定

在markdown中，我們可以使用
```
---xxx
---
```
的格式來設置一篇markdown文章的各項屬性，它一般寫在文章的最開頭位置；
可以在--- ---之間設置的文章屬性有：
1. title：文章的標題;
2. author：文章的作者;
3. date：文章的創建時間;
4. 添加導出配置（在后文中細說）；

2.2 標題

對照html的<h>內容</h>標簽，markdown的標題格式為：# 內容；
#號后面可以跟0-5個#號，表示標題的等級：
```
# 一級標題
## 二級標題
### 三級標題
#### 四級標題
##### 五級標題
###### 六級標題
```
展示效果是：

一級標題

二級標題

三級標題

四級標題

五級標題

六級標題

與html一致，你可以對每個標題設置特定的id和class，格式為：

## 測試標題{#title1 .class1} <!-- 設置id為title1，class1為標簽樣式 -->

在標題中也可以使用強調、高亮、刪除線等文字標記方法：
```
##### *測試斜體*
##### **測試粗體**
##### ~~測試刪除線~~
##### `測試代碼`
##### 測試下劃線
##### ==測試高亮==
```
效果為：
測試斜體

測試粗體

~~測試刪除線~~

測試代碼

測試下劃線

測試高亮

2.3 目錄

在Markdown Preview Enhanced中創建目錄有兩種方式：
1. 采用列表的形式，每個目錄項的格式是[目錄項名稱](#目錄項名稱)，例如：
```
- [1. 章節1](#章節1)- [1.1. 子章節1](#子章節1)
```
  效果是：
  - 1. 章節1
    - 1.1. 子章節1
2. 直接使用Markdown Preview Enhanced 支持的[TOC]，將其填在想要創建目錄的位置即可。例如：
```
[TOC]
### 1. 章節1
#### 1.1 子章節1.1
```
  效果是：
  
  值得注意的是：[TOC]是自動識別同一層級的所有標題并統計的，如果想要某個標題不被[TOC]統計，則可以在標題后添加 {ignore=true} ，便可在預覽和pdf界面的目錄中忽略它；

2.4 文字標記

對于markdown中的文字，可以使用各種各樣的方式進行修飾；

以下為一些實例：

**粗體**  
*斜體*
~~刪除線~~、{--刪除線--}
<u>下劃線</u>、<ins>下劃線</ins>、{++下劃線++}
==高亮==
`區域標記`
<big>變大</big>
<small>變小</small>
<span style="color:red" >自定義樣式</span>
這是^上標^
這是~下標~

其效果為：
粗體
斜體
~~刪除線~~
{++下劃線++}
高亮
區域標記
變大
變小
自定義樣式
這是^上標
這是_下標

2.5 注釋和引用

在markdown中，注釋和引用都是兩種備注形式，一般在大段外部文獻說明時使用引用，在案例或者自身理解、注疏時使用注釋；
注釋一般有三種:
1. 代碼塊:
 - 一般用于展示代碼或者分類說明；
 - 使用方式即：
```

```lang{cmd=your_cmd opt1=value1 opt2=value2 ...}
 相關代碼
```
- lang是指代碼塊中的代碼類型(如java,markdown,python)，markdown會根據代碼類型自動添加語法高亮；
- 如果你想執行代碼塊中的代碼，則需要在VS Code設置中檢索enableScriptExecution并打開為true。但是注意VS Code的腳本執行功能并不會保證代碼塊內代碼執行的安全性，如果你運行了他人的惡意代碼，就可能導致系統崩潰，數據被竊取等不良后果。所以這個設置一般是關閉的。打開之后，在{}內輸入cmd或者cmd=true、cmd="xxx"調用系統變量處預置的編輯器執行腳本；
- 如果你只想要執行后的結果不想要執行的代碼信息，可以在opt處改成hide = true或者hide，以省略代碼信息；
- 如果你想設置你的代碼效果，可以在opt處填寫output xxx，其中xxx可以是html，markdown，text，png（base64圖片）或者none(隱藏輸出結果) ；
- 如果你想唯一標識一段代碼段，可以給它添加id到opt處；
- 如果你想在代碼塊中看到代碼行數，可以在opt處填寫.line-numbers；
- 如果你想下一個代碼塊繼續執行上一個代碼塊的內容，可以在opt處填寫continue，這種情況默認是下一個繼續上一個的；如果你想繼續指定代碼塊的內容，可以使用continue its_id的形式，執行its_id的代碼塊內容;
- 如果你想在markdown文件被保存時自動運行代碼塊，則可以在opt處填寫run_on_save = true，其默認是false的；
- 如果你想直接插入代碼塊運行結果到markdown文件中，則可以在opt處填寫modify_source = true，其默認是false的；
- 如果你想高亮對應的代碼行數，可以在opt處填寫highlight=行數，其默認是false的；
一個簡單的例子是：
```
```python {cmd .line-numbers id="test1" highlight=2}
for i in range(10):a += i
print("The result is: %d" %a)
```
```
其結果是： 
```
2. 灰體注釋：
 - 在行首使用>并空一格，后邊的文字便可以背景灰化降低對比度象征內容的補充；
 - 例如：
```
> 這是灰體注釋
```
 效果是：
 
 這是灰體注釋
3. markdown內注釋：
 - 由于markdown與html互相兼容，因此可以在markdown內使用html的注釋標簽，在預覽時不會呈現到文檔中。VS Code對此的快捷鍵是ctrl + /;
 - 例如：
```

這是正文內容
```
引用又叫腳注，即我們在論文中常見的內容出處。在markdown上，我們可以使用[^x]來引用，例如：
```
Content [^1]
---
[^1]: Hi! This is a footnote
```
實際效果是：

其中，點擊[1]可以跳轉對應的引用，點擊返回鍵又可以跳轉回原有文章的位置；

2.6 縮寫

在markdown中，我們可以使用*[縮寫詞]: 全稱的方式來定義縮寫，并且在文章中使用對應的縮寫詞就可以在光標懸浮在縮寫詞上時彈出全稱浮窗；

例如：

*[HTML]: Hyper Text Markup LanguageHTML is the standard markup language for creating Web pages.

其顯示效果如下：

2.7 任務列表

markdown支持在文檔中使用未確認或已確認兩種形態的任務列表。
其形式如下：
```
- [x] 已確認形式
- [ ] 未確認形式（`記得空格`）
```
效果如下：
- 已確認形式
- 未確認形式（記得空格）

2.8 分割線與空行、空格

類似于HTML中的<hr>標簽或者Element-Plus中的<el-divider>，markdown支持在文檔中使用分割線;
其形式如下：
```

---
```
效果是：
值得注意的是：在一段文字下使用---不會在下方生成分割線，而是對文字進行放大，若要添加分割線需要空一行；

若要讓文字之間段間距提高，可以使用 標簽或者自定義塊的上下左右邊界，例如：

這是第一段
<br/>
這是第二段
<!-- margin-xxx意味著容器相對于其他容器的上下左右距離是多少，距離單位自行查閱html -->
<div style="margin-top: 20px;margin-left: 20px;">這是第三段</div>

其展示效果如下：
這是第一段

這是第二段

這是第三段

在markdown中添加空格有很多種形式，space或者tab均可以實現，但是不管輸入多少次都只能添加一個空格，如果要添加多個可以使用html的 ，例如：
```

前半部分 后半部分（`tab添加`）
前半部分 后半部分（`space添加`）

前半部分&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;后半部分
```
其效果為：
前半部分后半部分
前半部分后半部分

前半部分???????后半部分

2.9 列表

列表是markdown中的一個核心功能，分為有序列表和無序列表、定義列表三種；
無序列表有兩種實現方法：
1. 列表項前面加一個星號（*）或減號（-）,例如：
```
- 列表1
* 列表2
```
 其效果如下：
 - 列表1
 - 列表2
2. 使用html的標簽，例如：
```

<ul><li>列表1</li><li>列表2</li>
</ul>
```
 效果是一樣的；

有序列表也有兩種形式：

列表項前面加數字. ,例如：

<!-- 一般除了第一個外，markdown會自動填充的 -->
1. 列表項1
2. 列表項2

其效果為：

列表項1
列表項2

使用html的標簽，例如：

<!-- 表項的種類上，<ol>是有序列表，<ul>是無序列表，<li>是表項內容 -->
<ol><li>列表項1</li><li>列表項2</li><li>列表項3</li>
</ol>

其結果同上；

最后一種，也是寫文章中常用的定義列表，常用于定義某種命題或者概念；
- 其實現方法是使用html標簽，例如；
```

<dl><dt>術語1</dt><dd>術語1的解釋</dd><dt>術語2</dt><dd>術語2的解釋</dd>
</dl>
```
 其效果為：
 術語1
 術語1的解釋
 術語2
 術語2的解釋

2.10 表格

一般情況下，markdown的表格不允許合并行或列，除非你打開markdown-preview-enhanced的配置項 enableExtendedTableSyntax ，其默認是false；

表格通過|||進行分列，用換行表示分行，；例如：

<!-- 第二行用--注釋表格，用:表示對齊-->
<!-- 在左邊表示左對齊，在右邊表示右對齊，兩邊都有就居中對齊 -->
|aaaaa|bbbbb|ccccc|
<!-- 列對齊格式說明 -->
|:--|:--:|--:|
|c|d|e|
<!-- 默認左邊合并右邊空著的表格，格式遵循左邊的 -->
|a1||a2|
<!-- 如果是要右邊合并左邊的表格，則在左邊添加>符號，此時格式也遵循右邊 -->
|>|b1|b2|
|C1|C2||
<!-- 為了保持空表格不被合并，需要使用&nbsp;符號替代空格 -->
|D1|&nbsp;|D2|
|E1|E2|E3|
<!-- 上下合并需要在下方被合并的表格中添加^符號，且遵循同列的格式 -->
|^|F1|F2|

其效果是（）：

2.11 告誡塊

即我們常說的Admonition，用于在文檔中插入帶樣式的提示、警告、說明等信息；
其標準格式是：
```
!!! type 標題/問題內容/回答
```

其中type有以下幾種：

類型	樣式效果	使用場景
`note/primary/important`	淡藍色-筆	常規提醒
`info`	天青色-感嘆號	補充說明
`warning/caution`	淡橙色-感嘆號	提醒讀者注意
`tip/hint`	淡綠色-火焰	技巧/建議
`success`	淡綠色-打勾	表示操作成功的提示
`danger`	紅色-閃電	表示危險需要注意
`error/failure`	紅色-打叉	錯誤提示
`question`	綠色-問號	用于提問或者思考
`abstract`	藍色-段落	用于展示摘要
`quote`	灰色-引號	用于展示引用
`bug`	紅色-蟲子	用于描述bug
`example`	天青色-列表	用于舉例子

例如：

!!! question 中國有幾個省級行政單位？23個省、5個自治區、4個直轄市、2個特別行政區、1個地區

其效果是：

3. 特殊功能

3.1 數學、物理公式插入

在Markdown Preview Enhanced中默認使用KaTex或者MathJax進行公式渲染；
插入分為兩種：
1. 行內插入：
  - 使用 $···$ 或者$···$的格式進行插入;
  - 例如：
```
質能方程是$E=mc^2$
```
    其結果為：
    質能方程是 $E=mc^2$
2. 行外插入：
  - 使用 $$···$$ 或者\[···\]的格式進行插入;
  - 或者直接寫代碼塊
```
```math
    E=mc^2
```
```
    結果是： 
    $$E=mc^2$$  
```
插入的公式采用latex語法進行表述，以下將進行簡要介紹：

3.2 圖片、超鏈接插入

鏈接使用[···](···)的格式使用，如：
```
[百度](https://www.baidu.com)
```
效果是：
百度
圖片使用![外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=%C2%B7%C2%B7%C2%B7&pos_id=img-CY8HgDeT-1751874807233)的格式使用，如：
```
![圖片](https://i-blog.csdnimg.cn/img_convert/a807cbc37c464409643622f20f8eba5b.png)
```
效果是：
如果使用圖片的鏈接是本地的，則使用![外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=%E7%9B%B8%E5%AF%B9%E8%B7%AF%E5%BE%84&pos_id=img-ym2qcZbg-1751874807233)的格式使用，其中：
1. ./：當前目錄；
2. ../：上一級目錄；
3. folder/：指定目錄；