Md使用教程

Wed, 03 Jan 2024 10:34:15 +0800

平时写博客、记笔记都用 Markdown，语法碎，用到老忘，干脆整理一份放这儿，忘了就翻。下面全是能直接抄的写法，GitHub、Hugo、Obsidian 基本都支持。

标题

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

正文里一般用到三级就够了，堆太多层目录会很乱。

还有一种底线写法，效果跟一二级标题一样：

标题一
======

标题二
------

文字样式

**加粗**
*斜体*
***加粗加斜体***
~~删除线~~
==高亮==
`行内代码`

几个要注意的：

==高亮== 不是所有渲染器都开，Hugo 默认可能不显示，别当主力用。
想加下划线直接写 <u>下划线</u>，Markdown 本身没这个语法。
上下标靠 HTML：H₂O、X²。

段落和换行

段与段之间空一行，不然会被并成一段。

想在同一段里换行，句尾打两个空格再回车；嫌麻烦就直接空一行分段落。

引用

> 这是引用内容
> 第二行也是引用

> 第一层
>> 嵌套第二层
>>> 再套一层

列表

无序列表，-、+、* 都行，我习惯用 -：

- 第一项
- 第二项
  - 子项，前面缩进两个空格
  - 另一个子项
    - 再往下一层

有序列表：

1
2
3

1. 第一件
2. 第二件
3. 第三件

手写序号其实无所谓，渲染出来会自动排，1. 1. 1. 也能变成 1、2、3。

任务清单（GitHub、Hugo 支持）：

1
2
3

- [x] 已经做完的
- [ ] 还没做的
- [ ] 待办

分割线

1
2
3

---
***
___

三种写法效果一样，用 --- 就行。

链接

1
2

[点这里去百度](https://www.baidu.com)
[带悬浮提示的链接](https://www.baidu.com "鼠标放上去显示这句话")

直接贴网址也能识别，保险起见包一层 <>：

`1`	`<https://www.baidu.com>`

引用式链接，长文里链接多了用这个，正文看着干净：

1
2
3

看这个说明[去官网][1]。

[1]: https://www.example.com "官网"

图片

1
2

![图片加载不出来时显示的字](https://xxx.com/a.png)
![带标题的图](https://xxx.com/a.png "鼠标悬浮显示")

本地图就把路径换成相对路径，Hugo 里一般放 assets 或 static 目录。

代码块

行内代码用一对反引号包起来：

`1`	`print("hello")`

整段代码块用三个反引号，后面跟语言名，能高亮：

```python
def hello():
    print("hi")
```

常用语言名：python、javascript、bash、html、yaml、sql。

踩坑：如果代码块里本身要出现三个反引号，外层就得用四个反引号包，不然会提前结束。

表格

```md

姓名	年龄	职业
张三	20	学生
李四	22	程序员


对齐方式靠第二行的冒号控制：

```md
| 左对齐 | 居中 | 右对齐 |
| :----- | :--: | -----: |
| a      |  b   |      c |

表格两边的竖线漏写也能渲染，但建议写全，自己看着清楚。

脚注

正文标个记号，文末写解释，GitHub 和 Hugo 都支持：

1
2
3

这句话后面加个脚注[^1]。

[^1]: 脚注的具体内容，可以写很长。

注释

写了但页面上看不见，用来给自己留备忘：

`1`	`<!-- 这里是注释，渲染后不会显示 -->`

转义字符

想让符号原样显示而不被解析，前面加个反斜杠：

1
2
3

\*这不是斜体\*
\# 这不是标题
\` 这是普通的反引号

需要转义的主要是这些：\、反引号、*、_、{}、[]、()、#、+、-、.、!、|。

折叠块

长内容不想全摊开，用 details 收起来：

<details>
<summary>点我展开</summary>
这里是隐藏的内容，默认折叠。
</details>

嵌入 HTML

Markdown 里可以直接写 HTML，不受限制：

1
2

<br> 换行
<p>一个段落</p>

不过能用 Markdown 解决的就别写 HTML，兼容性好。

常用但别乱用的

[TOC] 自动生成目录，不同主题支持不一样，Stack 主题自己有目录，一般不用写。
:emoji: 这种写法在 GitHub 上能出表情，本地编辑器未必识别。

几条个人习惯

段落之间一定空一行，不空容易出奇怪的合并。
代码块语言名记得写，不然没有高亮。
图片先想好 alt 文字，图挂了也知道是什么。
表格写完本地预览一遍，对齐歪了自己都难受。

建站 on 寻 Mi 处