Markdown 文档编辑

Function Lv1
  2026-03-16 23:24:31 2026-03-16 23:24:31 创建   2026-03-21 15:41:08 2026-03-21 15:41:08 更新  

Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档。
Markdown 编写的文档后缀为 .md, .markdown。

重要的是，在 Markdown 中你可以直接使用 HTML 标签，这为复杂格式提供了灵活性。当 Markdown 的基础语法无法满足需求时，可以嵌入 HTML 代码来实现特定效果。

一、Markdown 工具

工欲善其事，必先利其器

1、专业代码编辑器

  • VScode
    • Markdown All in One：提供快捷键、目录生成、数学公式支持
    • Markdown Preview Enhanced：增强的预览功能，支持图表和演示模式
  • Obsidian

2、专门的 Markdown 编辑器

  • Mark Text
  • Zettlr
  • Typora

二、Markdown 标题

1
2
3
4
5
6
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

1、重要注意事项：

符号与文字间的空格：# 号和标题文字之间必须有一个空格。这是标准的 Markdown 语法要求。

唯一的一级标题：在一个文档中，通常只使用一个一级标题作为文档的主标题，这符合良好的文档结构规范。

2、标题的嵌套结构

标题的层次结构应该遵循逻辑顺序，不应该跳级使用。良好的标题结构就像一本书的目录

三、Markdown 文本格式

段落的换行是使用两个以上空格加上回车。

1、字体

  • 粗体语法：用一对**或者__包围文字
  • 斜体语法：用一对*或者一个下划线_包围文字
  • 粗斜体语法：用一对***或者___包围文字

不要过度使用强调，重点突出才有效果。
在中英文混合时，建议在强调符号前后加空格以提高可读性。

2、分割线

三个以上的减号或者星号

1
2
***
---------

3、删除线

如果段落上的文字要添加删除线，只需要在文字的两端加上两个波浪线 ~~ 即可

1
~~这是一个错误示例~~

4、下划线

下划线可通过HTML的<u>标签来实现

1
<u>带下划线文本</u>

5、脚注

脚注是对文本的补充说明。

1
2
3
创建一个脚注类型是这样的 [^1]

[^1]:这是一个脚注

6、行内代码

行内代码用于在正文中标记代码片段、命令、变量名等：

1
2
3
使用 `git commit` 命令提交代码
变量 `userName` 存储用户名
在终端输入 `npm install` 安装依赖
  • 包含反引号的代码：当代码本身包含反引号时，使用两个反引号包围。

应用场景：

  • 技术文档中的 API 名称、函数名
  • 配置文件中的参数名
  • 命令行指令
  • 键盘快捷键（如 Ctrl+C）

7、段落与换行

段落基本规则：

  • 段落由一个或多个连续的文本行组成
  • 段落之间由一个或多个空行分隔
  • 普通段落不应该用空格或制表符缩进
1
2
3
4
5
这是第一段
这是第二段（错误：没有空行分隔）

    这是缩进段落（错误：不应该缩进）

强制换行技巧：

  • shift+enter

四、Markdown 列表

Markdown支持有序列表和无序列表

1、无序列表

用+、-、*后面再添加一个空格，然后写内容

1
2
3
+ 第一项
- 第二项
* 第三项

选择建议：

  • 建议统一使用减号 ，因为它在视觉上更清晰
  • 在同一文档中保持一致的标记方式
  • 标记符号后必须有一个空格

2、有序列表

有序列表是数字加上.号来表示

1
2
3
1. 第一项
2. 第二项
3. 第三项
  • 数字可以不连续
1
2
3
1. 第一项
2. 第二项
6. 第三项 (其实是3)
  • 也可以从指定数字开始

3、列表嵌套

1
2
3
4
5
1. 第一项
	 - 第一项的任务
	 - 第二项的任务
		 1. 任务1步骤
		 2. 任务2步骤

嵌套规则：

  • 子列表需要缩进 2-4 个空格（推荐 2 个）
  • 保持一致的缩进长度
  • 可以无限层嵌套，但实际使用中建议不超过 3 层

4、任务列表（复选框列表）

使用- [] 代表未完成，用- [x] 代表已完成。

1
2
- [] 未完成任务
- [x] 已完成任务

使用技巧：

  • 方括号内的空格和 x 很重要：[ ] 和 [x]
  • 可以与嵌套列表结合使用
  • 在项目管理、学习计划、生活清单中特别有用
  • 某些编辑器支持点击复选框来切换状态

五、Markdown 引用块

引用块用于突出显示重要信息、引用他人观点或创建视觉层次。

1、单行引用

使用> 后面跟一个空格

这是一个单引用

这是个长引用
包含多行内容
只需要在第一行中写> 即可

2、多级嵌套引用

1
2
3
> 最外层
>> 第一层嵌套
>>> 第二层嵌套

3、列表使用区块

如果要在列表项目内放进区块，那么就需要在 > 前添加四个空格的缩进。

1
2
3
4
1. 第一项
    > 空四格
    > 嵌套
2. 第二项

引用的最佳实践

  • 重要信息提示
  • 错误信息
  • 信息提示
  • 警告信息

文档结构中的引用

  • 章节摘要：
1
2
3
4
5
6
7
# 第一章：项目概述

> **本章要点**
> 
> - 了解项目背景和目标
> - 掌握核心功能特性
> - 熟悉技术架构设计
  • 版本更新说明：
1
2
3
4
5
6
7
## v2.1.0 更新内容

> **重大变更**
> 
> &#x26a0;&#xfe0f; API 接口路径已调整，旧版本客户端需要更新
> 
> 详见 [迁移指南](./migration-guide.md)

六、Markdown代码

  • 使用```包裹为单行代码块
  • 使用`````包裹为多行代码块（可在三反引号后面添加语言标识）
1
2
3
```bash
npm install
npm start
1
2
3
4
5

**使用双反引号包围单反引号：**

```bash
``使用`反引号`包围代码``

使用多个反引号包围：

1
```包含 `` 双反引号的代码```

1、代码区块

  • 缩进式代码块

代码区块使用 4 个空格或者一个制表符（Tab 键）

1
2
3
4
5
6
7
正常文本段落

		这是缩进式代码块
    每行前面有四个空格
    保持代码的原始格式
    
继续正常文本

七、Markdown 链接

1
2
3
[链接名称]（链接地址）
[链接文字]（链接地址 "可选的标题"）
<链接地址>
1
2
3
这是一个[notion](https://www.notion.com/)链接
这是个[链接](https://www.notion.com/ "这是个notion官网地址")
<https://www.notion.com/>

1、参考链接

参考式链接将链接定义与使用分离，让文档更整洁，特别适合长文档或需要多次引用相同链接的情况。

1
2
3
markdown[链接文字][参考标签]

[参考标签]: URL "可选标题"
1
2
3
4
5
6
这个链接用1作为网址变量[Google][1]
这个链接用notion作为网址变量[官网][notion]
然后在文档结尾为参考标签赋值

[1]:https://www.google.com/ "这是Google官网"
[notion]:https://www.notion.com/ "这是notion官网"

当参考标签和链接文字是一样时，参考标签只需写一对[] 即可

参考链接的优势：

  • 文档正文更清爽，不被长 URL 打断
  • 便于链接的统一管理和更新
  • 相同链接可以重复使用，避免重复定义
  • 链接定义可以放在文档任意位置（通常放在末尾）

2、锚点链接的使用

锚点链接用于在同一文档内跳转，特别适合长文档的导航

1
2
3
4
5
6
7
8
9
10
11
# 目录
- [第一章:介绍](#第一章介绍)
- [第二章:安装](#第二章安装)
- [第三章:使用说明](#第三章使用说明)

## 第一章：介绍
这是介绍
## 第二章：安装
这是安装
## 第三章：使用说明
这是使用说明

八、Markdown 图片

图片能让文档更加生动和易于理解。

Markdown 图片语法格式如下：

1
2
![替代文字](图片路径)
![替代文字](图片路径 "图片标题")
  • 开头一个感叹号 !
  • 接着一个方括号，里面放上图片的替代文字
  • 接着一个普通括号，里面放上图片的网址，最后还可以用引号包住并加上选择性的 ‘title’ 属性的文字。

强烈建议使用相对路径

路径使用建议：

  • 推荐使用相对路径，便于项目移植
  • 建议创建专门的图片文件夹（如 images/、assets/）
  • 使用有意义的文件名，便于管理
  • 注意路径分隔符在不同操作系统中的差异

Alt 文本（替代文字）在图片无法显示时提供替代信息，同时对无障碍访问和 SEO 很重要

alt 文本最佳实践：

  • 简洁但有描述性
  • 描述图片的主要内容和用途
  • 避免使用”图片”、”照片”等冗余词汇
  • 对于装饰性图片，可以使用空的 alt 文本
  • 考虑上下文，提供有意义的信息

1、图片链接组合

将图片作为链接的可点击元素。

1
[![图片alt文本](图片URL)](链接URL)

九、Markdown 表格

表格和引用是 Markdown 中重要的内容组织工具。

表格能够清晰地展示结构化数据，而引用则用于突出重要信息或引用他人观点。

使用|和-构成表格

语法要点：

  • 表头和数据行之间必须有分隔线
  • 分隔线至少需要三个连字符 --
  • 两端的竖线 | 是可选的，但建议保留以提高可读性
  • 不需要严格对齐，但对齐后更美观
1
2
3
| 表头 | 表头 |
| ---- | ---- |
| 内容 | 内容 |

1、对齐方式

我们可以设置表格的对齐方式：

  • **--:** 设置内容和标题栏居右对齐。
  • **:---** 设置内容和标题栏居左对齐。
  • :---: 设置内容和标题栏居中对齐。

2、复杂表格的处理技巧

在表格内可使用大部分Markdown语法

1
2
3
4
5
6
| 功能 | 描述 | 状态 |
| ---- | ---- | ---- |
|**用户登录**| 支持手机和邮箱 | 完成 |
|*密码重置*| 通过邮箱重置密码 | 完成 |
|`API接口`| API设计 | 完成 |
| [文档链接](https://www.notion.com/) | 网址入口 | 完成 |

换行处理在后面添加<br>

  • 标题: Markdown 文档编辑
  • 作者: Function
  • 创建于 : 2026-03-16 23:24:31
  • 更新于 : 2026-03-21 15:41:08
  • 链接: https://redefine.ohevan.com/2026/03/16/Markdown手册/
  • 版权声明: 本文章采用 CC BY-NC-SA 4.0 进行许可。
评论
目录
Markdown 文档编辑
  1. 一、Markdown 工具
    1. 1、专业代码编辑器
    2. 2、专门的 Markdown 编辑器
  2. 二、Markdown 标题
    1. 1、重要注意事项：
    2. 2、标题的嵌套结构
  3. 三、Markdown 文本格式
    1. 1、字体
    2. 2、分割线
    3. 3、删除线
    4. 4、下划线
    5. 5、脚注
    6. 6、行内代码
    7. 7、段落与换行
  4. 四、Markdown 列表
    1. 1、无序列表
    2. 2、有序列表
    3. 3、列表嵌套
    4. 4、任务列表（复选框列表）
  5. 五、Markdown 引用块
    1. 1、单行引用
    2. 2、多级嵌套引用
    3. 3、列表使用区块
  6. 六、Markdown代码
    1. 1、代码区块
  7. 七、Markdown 链接
    1. 1、参考链接
    2. 2、锚点链接的使用
  8. 八、Markdown 图片
    1. 1、图片链接组合
  9. 九、Markdown 表格
    1. 1、对齐方式
    2. 2、复杂表格的处理技巧