S00-00 General-Markdown

• 概述
  • 什么是 Markdown
  • 基础语法
  • 进阶功能
  • 优点
  • 缺点
• 常用语法
  • 标题
  • 文本样式
  • 列表
    • 无序列表
    • 有序列表
  • 链接与图片
    • 超链接
    • 图片
  • 引用
  • 代码块
  • 分割线
  • 进阶常用：表格
  • 进阶常用：任务列表
    • 语法
      • 基本构成
      • 严格的空格规则
      • 正确/错误示例
    • 嵌套语法
    • 底层渲染原理
    • 常见“坑”与排查清单
  • 避坑指南
• 扩展功能
  • Typora 软换行

[TOC]

概述

什么是 Markdown

Markdown：是一种轻量级的标记语言（Markup Language），它允许人们使用易读易写的纯文本格式编写文档，然后将其转换成有效的 XHTML（或者 HTML）。

简单来说，Markdown 就是一种给文本添加格式的方法，但你不需要像在 Word 里那样点击按钮，而是通过键盘输入的符号（如 #、*、-）来控制排版。

以下是它的核心特点和常见用法：

核心理念：易读易写：Markdown 的设计初衷是让文档在“纯文本”状态下也是可读的。即使不渲染成漂亮的网页，直接看源码也能看懂结构。

基础语法

测试	描述
test	desc

Markdown 的语法非常直观，以下是源码与效果的对比：

你的输入 (Markdown 源码)	最终显示效果 (渲染后)
# 这是一个标题	(一级大标题)
## 这是一个副标题	(二级副标题)
**这段文字加粗**	这段文字加粗
*这段文字斜体*	这段文字斜体
- 这是一个列表项	• 这是一个列表项
> 这是一段引用	(缩进的引用块)
code	code (行内代码)
[Google](https://google.com)	Google (超链接)

进阶功能

进阶功能：

现代的 Markdown 编辑器通常支持更丰富的功能（有时被称为 Markdown 的“方言”或扩展语法），例如：

• 代码块高亮：支持 Python, JavaScript 等语言的语法高亮。
• 数学公式：使用 LaTeX 语法编写公式。
• 表格：虽然原生语法较繁琐，但大部分编辑器都支持。
• 流程图/时序图：如 Mermaid 语法。

优点

Markdown 的优点：

• 专注写作：双手不用离开键盘去调整排版，可以保持心流。
• 兼容性强：本质是纯文本（.md 文件），任何操作系统、任何文本编辑器（记事本、VS Code）都能打开。
• 格式转换方便：可以轻松导出为 HTML、PDF、Word 等格式。
• 开发者友好：Github、GitLab 等平台的 README.md 文件都使用它，程序员写技术文档的首选。

缺点

Markdown 的缺点：

Markdown 确实非常流行，但它并非万能。它的设计初衷是**“轻量级”和“易读性”**，这在带来便利的同时，也牺牲了许多功能。

以下是 Markdown 的主要缺点和限制，了解这些可以帮你判断它是否适合你的需求：

1. 排版和样式能力非常有限：

   这是 Markdown 最大的短板。它只关注内容结构（这是标题、那是列表），而不关注视觉呈现。

   • 无法调整字体/颜色/大小：你不能像在 Word 里那样选中文字然后改成“红色、20 号字、宋体”。
   • 对齐方式单一：原生语法通常不支持文本居中或右对齐（需要写 HTML 标签来实现）。
   • 图片调整困难：原生语法只能插入图片 ![]()，无法直接调整图片的大小（长宽）、位置（居中/左环绕）。
     • 解决办法：通常只能嵌入 HTML 代码，如 <img src="..." width="50%">，但这违背了“纯文本易读”的初衷。

2. 表格功能较弱：

   虽然大多数编辑器都支持 Markdown 表格，但体验远不如 Excel 或 Word。

   • 语法繁琐：手动输入 |---|---| 这种符号来画表格非常痛苦，稍微错位一点就很难看（虽然有插件辅助）。
   • 不支持复杂结构：无法实现合并单元格（跨行或跨列），也不支持单元格内的复杂排版（如单元格内换行、插入列表）。

3. 标准分裂：

   Markdown 没有一个绝对统一的官方标准。虽然有 CommonMark 试图标准化，但各家平台都在根据自己的需求“魔改”。

   • 语法不兼容：
     • 在 GitHub 上能用的语法（如任务列表 -[ ]），搬到原本的 Markdown 解释器里可能就不认了。
     • 数学公式在 Obsidian 里用的是 $$，在某些博客平台可能需要特定的插件。
   • 这导致同一个 .md 文件，在不同软件里打开，渲染效果可能不一样。

4. 对非技术人员有门槛：

   虽然号称“简单”，但对于习惯了 Word “所见即所得”（WYSIWYG）的用户来说，依然有学习成本。

   • 记忆负担：你需要记住 * 是斜体，** 是加粗，> 是引用。
   • “盲写”的不安全感：在纯文本编辑器中，你必须等到渲染预览后，才知道自己有没有写错（比如少了一个空格导致列表没生效）。

5. 资源管理不便：

   Markdown 是纯文本文件，它不包含图片。

   • 如果你在文档里插入一张图片，实际上只是插入了一个“链接”。
   • 如果你把这个 .md 文件发给朋友，却忘了把图片文件一起打包发过去（或者图片链接失效了），对方看到的文档里图片就会变成一个裂开的图标。
   • 相比之下，Word (.docx) 是把图片直接打包在文档内部的，复制粘贴更方便。

6. 总结：什么时候不该用 Markdown？：

   • 需要精美排版时：比如制作简历（除非你精通 CSS）、宣传海报、复杂的商务报告。
   • 需要复杂表格时：比如财务报表。
   • 文档需要频繁分享给“非技术人员”时：直接发 Word 或 PDF 会更体面、更安全。

Markdown 最适合的场景依然是：个人笔记、技术文档、博客文章、以及任何主要关注“内容”而非“形式”的写作。

常用语法

这份指南将按使用频率为你介绍 Markdown 的常用语法。你可以把它当作一份“速查表”来收藏。

Markdown 的基本逻辑是：左边是符号，右边是内容。

标题

使用 # 号来表示标题，# 的数量代表标题的级别（从 h1 到 h6）。

注意：# 和文字之间必须有一个空格。

写法	效果
# 一级标题	(最大号标题)
## 二级标题	(次大号标题)
### 三级标题	(三级标题，依此类推)

文本样式

用来强调文字的重点。

写法	效果	说明
**加粗**	加粗	最常用，两侧各两个星号
*斜体*	斜体	两侧各一个星号
~~删除线~~	删除线	两侧各两个波浪号
代码	代码	行内代码，用反引号(键盘左上角)

列表

列表分为有序和无序两种。

无序列表

使用 -、* 或 + 加上空格。

- 苹果
- 香蕉
  - 这里的缩进表示子列表（按 Tab 键或输入 2 个空格）

效果：

• 苹果
• 香蕉
  • 这里的缩进表示子列表

有序列表

使用数字加点 1. 加上空格。

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

效果：

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

链接与图片

这两个语法非常像，图片只多了一个感叹号 !。

超链接

语法：[显示文本](链接地址)

• 写法：[Google](https://google.com)
• 效果：Google

图片

语法：![图片描述](图片链接)

• 写法：![Markdown logo](https://markdown-here.com/img/icon256.png)
• 注意：图片描述（Alt text）是当图片无法加载时显示的文字，也是给屏幕阅读器读的。

引用

用于引用他人的话，或者表示强调的段落。使用 > 符号。

> 这是一段引用。
>
> 即使换行了，这也是引用的一部分。
>
> > 这里是嵌套引用。

效果：

这是一段引用。

即使换行了，这也是引用的一部分。

这里是嵌套引用。

代码块

这是程序员最喜欢的功能。使用三个反引号 ``` 包裹代码。

你可以在反引号后面指定语言（如 python, js, html），编辑器会进行语法高亮。

写法：

```python
print("Hello World")
def add(a, b):
    return a + b
```

效果：

print("Hello World")
def add(a, b):
    return a + b

分割线

用于在文档中划分章节。

使用三个或更多的 - 或 *。

写法： --- 或 ***

效果：

(见下方细线)

进阶常用：表格

虽然稍显麻烦，但用来展示简单数据很有用。

使用 | 分隔列，使用 - 分隔表头。

写法：

| 姓名  | 年龄 |   职业 |
| :---- | :--: | -----: |
| Alice |  20  | 设计师 |
| Bob   |  30  | 工程师 |

注：第二行冒号的位置决定对齐方式（左边是左对齐，两边是居中，右边是右对齐）。

效果：

姓名	年龄	职业
Alice	20	设计师
Bob	30	工程师

进阶常用：任务列表

结合我们之前的对话，特别是你发现 VitePress 需要配置插件 这一关键点，我为你整理了一份关于 Markdown 任务列表 (Task List) 的终极指南。

这份指南将从标准语法规范出发，并涵盖底层渲染原理（解释为什么有的地方能用，有的地方不能用）。

语法

Markdown 的任务列表语法由 GFM (GitHub Flavored Markdown) 定义。它的规则非常简单，但对格式要求极为严格。

基本构成

一个标准的任务列表项由三个部分组成，缺一不可：

1. 无序列表符：-、* 或 +（推荐统一使用 -）。
2. 状态标记：[ ]（未完成）或 [x]（已完成）。
3. 文本内容。

严格的空格规则

这是最容易出错的地方，请务必注意以下红色的空格位：

- [ ] 任务文本
↑  ↑ ↑
1  2 3

1. 列表符后：必须有一个空格。
2. 方括号内：

• 未完成：必须是一个标准英文空格 (U+0020)。不能是空（[]），也不能是全角空格。
• 已完成：必须是 x (大小写通常都兼容，但推荐小写)。

3. 方括号后：必须有一个空格，才能接文本。

正确/错误示例

源码 (Source)	渲染结果	说明
- [ ] 待办	✅ 复选框	标准写法
- [x] 完成	✅ 打钩框	标准写法
- [] 错误	❌ 纯文本	方括号中间少空格
-[ ] 错误	❌ 纯文本	减号后面少空格
- [ ]错误	❌ 纯文本	方括号后面少空格
- [v] 错误	❌ 纯文本	不支持 v，只能用 x
- [OK] 错误	❌ 纯文本	不支持自定义字符

嵌套语法

任务列表支持层级结构，这对于做项目拆解非常有用。

• 缩进规则：子任务必须比父任务多缩进 2 个或 4 个空格（取决于解析器设置，通常推荐 2 个空格）。
• 混合使用：复选框可以和普通的无序列表（•）混合使用。

- [ ] 父任务：准备发布
  - [x] 子任务 1：代码审查 (缩进 2 空格)
  - [ ] 子任务 2：编写文档
    - 普通列表项说明 (也可以混用普通列表)

底层渲染原理

这是我们之前排查的核心。Markdown 源码只是文本，它需要通过解析器（Parser）转换成 HTML 才能在网页上显示。

场景 A：开箱即用 (GitHub, VS Code, Obsidian)：

这些平台内置的解析器已经默认开启了 GFM 扩展支持。

• 它们将 - [ ] 解析为 <input type="checkbox">。
• 它们通常会给 <li> 加上 class="task-list-item"，并设置 list-style: none 去掉原本的圆点 •。

场景 B：原生标准库 (VitePress, 纯 markdown-it)：

VitePress 使用的是 markdown-it 解析器。markdown-it 的核心库是非常精简的，它默认并不包含任务列表的解析规则。

这就是为什么你在未安装插件时：

1. 解析器把 - [ ] 识别为普通的无序列表（所以保留了圆点 •）。
2. 解析器不认识 [ ] 语法，将其视为纯文本直接显示。

解决方案（你已验证）： 必须手动“挂载”这个解析规则：

1. 安装 npm install -D markdown-it-task-lists
2. 在 VitePress 配置中注册：md.use(taskLists)

常见“坑”与排查清单

如果你以后发现任务列表又失效了（显示为源码或带圆点的文本），请按此清单排查：

1. 环境支持度：当前软件（或博客框架）安装了任务列表插件吗？
2. 幽灵字符：是从别处复制的吗？如果是，方括号里的空格可能变成了   (不换行空格)。删掉括号里的内容，手动敲一个空格试试。
3. 自定义字符：你是不是写了 [?] 或 [!]？标准语法不支持这些，必须回退到 Emoji（如 ✅ 🚧）。
4. 松散列表 (Loose Lists)：

• 尽量不要在任务列表项之间加空行。
• 加了空行会导致每一项被 <p> 标签包裹（如 <li><p><input...></p></li>），在某些 CSS 主题下会导致对齐错乱或圆点无法消除。

总结： Markdown 的任务列表看似简单，其实依赖于严格的空格语法和特定解析器插件的支持。只要满足这两点，它就是一个非常强大的工具。

常用于做 To-Do List。

写法：

- [x] 已完成的任务 (中括号里是 x)
- [ ] 待办任务 (中括号里是空格)

效果：

• 已完成的任务
• 待办任务

避坑指南

1. 空格很重要：绝大多数符号（如 #, -, 1., >）后面必须跟一个空格才能生效。
   • ✅ 正确：# 标题
   • ❌ 错误：#标题
2. 换行机制：在某些严格的 Markdown 标准中，源码里换一次行，渲染出来可能还是同一行。要想在显示时强制换行，你需要在行尾加两个空格再回车，或者直接回车两次（形成空行，变成新段落）。
3. 符号转义：如果你想显示 * 这个符号本身，而不是让字变斜体，你需要在它前面加反斜杠 \。
   • 输入：\*这不是斜体\* -> 显示：这不是斜体

你想找个地方立刻练习一下这些语法吗？我可以推荐几个好用的在线编辑器。

扩展功能

Typora 软换行

Typora 软换行：

• 问题：编写的 markdown 内容在 vitepress 网页中显示时会出现以下效果：

  

• 分析：查看 markdown 源码，会发现源码中会有空白行间隔，该空白行会被渲染成 <p> 标签，包裹住后面内容。p 标签在 vitepress 网页中有 10px 的 margin 样式，所以才显示如此

  

• 解决：使用 2个空格 + 软换行
  在 Typora 中准备换行的位置编辑2个空格，再按Shift + Enter键进行软换行，此时 markdown 源码如下：

  

  渲染效果如图：