Neoverse-Docs

1.8 Markdown

掌握 Markdown 标记语言，用纯文本高效编写结构化文档

主要编写者：
ShenshijunShenshijun
本节 AI 摘要

本节介绍 Markdown 的常用语法：标题、段落、强调、列表、链接、图片、代码块、表格、引用，以及 GFM 扩展与本站增强语法（提示框、折叠块）。掌握后即可用纯文本写出结构清晰的文档。

INFO

GitHub 的 README、技术博客、API 文档、甚至正在阅读的这份文档——背后都是 Markdown。 它用少量标记为纯文本添加标题、列表、链接和代码块，语法容易上手，也便于版本控制。本节是后续编写技术文档、课程笔记和项目 README 的基础。

一、Markdown 是什么

Markdown 是一种轻量级标记语言：用 #、*、-、[ ] 等少量符号，就能为纯文本添加标题、列表、链接和代码块等结构。源文件仍是纯文本（后缀通常是 .md），渲染后则是排版整齐的文档。

正是这种“纯文本、可结构化”的特性，让它在技术写作中几乎成了默认选项：

  • 写笔记：比 Word 轻便，比 TXT 有结构
  • 写文档：README、API 文档和技术方案都常用它
  • 写博客：GitHub Pages、Hexo、Hugo 等工具都能使用 Markdown 作为内容源

Markdown 与 Word 的区别

Markdown 不是 Word 的替代品，它的目标是“让纯文本也能有结构”。 它不适合做复杂排版（海报、杂志），但非常适合写技术文档、笔记、README。

二、基础语法

2.1 标题

用 # 表示标题，数量对应层级：

Markdown
# 一级标题
## 二级标题
### 三级标题
#### 四级标题

本项目的标题规范

本项目规定文档标题从 H2 (##) 开始，因为 H1 由 frontmatter 的 title 字段渲染。详见 贡献指南。

2.2 段落与换行

Markdown 中，段落之间需要 空一行。只按一次回车（没有空行）会被当作同一段落内的软换行，渲染时可能被合并。

Markdown
这是第一段。

这是第二段。

2.3 强调

语法效果用途
**粗体**粗体强调重点
*斜体*斜体引用术语
`行内代码`行内代码标识代码
~~删除线~~删除线标记废弃

2.4 列表

无序列表用 -、* 或 +：

Markdown
- 第一项
- 第二项
    - 嵌套子项（缩进到父列表内容之后）
    - 另一个子项
- 第三项

有序列表用数字加点：

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

有序列表的自动编号

即使把有序列表写成 1. 1. 1.，渲染时也会自动变成 1. 2. 3.。但为了源码可读性，建议按顺序写。

2.5 链接与图片

Markdown
[链接文字](https://example.com)
![图片描述](图片路径或URL)

图片语法比链接多一个 !。图片描述会用于替代文本，路径可以是相对路径或 URL；路径包含空格等特殊字符时，需要按目标渲染器的规则转义或编码。

2.6 引用

用 > 表示引用：

Markdown
> 这是一段引用。
> 可以跨多行。

效果：

这是一段引用。 可以跨多行。

2.7 分隔线

用三个或以上的 - 或 *：

Markdown
---

技术文档经常使用代码块和表格，下面分别说明。

三、代码块

3.1 行内代码

用反引号包裹：`code` 效果为 code。

3.2 代码块

用三个反引号包裹，并在第一行指定语言以启用语法高亮：

Markdown
```python
def hello():
    print("Hello, World!")
```

效果：

Python
def hello():
    print("Hello, World!")

务必标注语言

标注语言（如 python、cpp、bash）能让渲染器正确高亮，大幅提升可读性。本项目对所有代码块的语言标识有要求，详见 贡献指南。

3.3 在代码块中显示反引号

当代码内容本身包含三反引号时，外层用四个反引号包裹：

Markdown
````markdown
```python
print("内部代码块")
```
````

四、表格

GFM 等常见扩展使用 | 分列，并用分隔行区分表头和内容：

Markdown
| 姓名 | 年龄 | 专业     |
| :--- | :---: | -------: |
| SSJ | 20  | 计算机   |
| SSSJ | 21  | 软件     |

效果：

姓名年龄专业
SSJ20计算机
SSSJ21软件

对齐方式：

语法对齐方式
:---左对齐
:---:居中
---:右对齐
表格格式化小贴士

不必手动对齐 | 的间距，渲染时会自动处理。源码对齐有助于阅读；若使用格式化扩展，安装前应确认发布者、权限和项目格式约定。

五、任务列表

Markdown
- [x] 已完成的任务
- [ ] 未完成的任务
- [ ] 另一个未完成任务

适合写待办清单、实践清单。

六、转义字符

Markdown 支持用反斜杠转义部分 ASCII 标点。字符能否转义以及是否需要转义取决于所在语法位置；例如表格中的 | 通常需要转义：

Markdown
\*这不是斜体\*    \# 这不是标题

效果：*这不是斜体* # 这不是标题

需转义的字符转义写法
*\*
#\#
``
`\`
_\_

不同平台会在核心语法上增加表格、任务列表、公式等扩展，兼容性以目标渲染器为准。

七、扩展语法

不同 Markdown 渲染器支持不同的扩展语法，这里介绍常用的几种。

7.1 GitHub Flavored Markdown（GFM）

GitHub Flavored Markdown（GFM）以 CommonMark 为基础增加了一组扩展，本项目也启用了常用的 GFM 语法，包括：

  • 任务列表（见上）
  • 表格（见上）
  • 删除线 (~~文字~~)
  • 自动链接（URL 自动变成链接）

7.2 警告框（Alert / Callout）

本项目使用 GitHub 风格的 alert，不同类型对应不同样式：

Markdown
> [!NOTE]
> 这是一个提示。

> [!TIP]
> 这是一个建议。

> [!WARNING]
> 这是一个警告。

> [!IMPORTANT]
> 这是一个重要信息。

7.3 可折叠详情块

本项目还提供适合答案、补充说明和较长示例的折叠块：

Markdown
> [!DETAILS-HINT] 查看提示
> 这里放不影响主线阅读的补充信息。

> [!DETAILS-ANSWER] 查看答案
> 这里放练习答案或参考实现。
什么时候使用折叠块？

主线阅读必须知道的内容直接写在正文或普通提示框中；答案、长示例和可选背景知识适合折叠，避免正文被次要信息打断。

7.4 数学公式

部分平台（比如本项目）支持 LaTeX 语法的数学公式，用 $ 包裹：

Markdown
行内公式: $E = mc^2$

块级公式:
$$
\int_0^1 x^2 dx = \frac{1}{3}
$$

数学公式的兼容性

数学公式不是所有 Markdown 渲染器都支持。GitHub 已支持，但部分平台需要额外插件。在写文档前，先确认目标平台是否支持。

除了语法正确，技术文档还需要清晰的结构和可验证的示例。

八、写作规范

8.1 结构清晰

  • 一篇文章只用一个 H1（本项目不用 H1，从 H2 开始）
  • 层级不要跳过（H2 后直接 H4 是坏习惯）
  • 每节内容聚焦一个主题，不贪多

8.2 中英文排版

中文与英文、数字之间加一个半角空格，提升可读性：

Markdown
# 好
使用 Python 3.12 编写程序

# 差
使用Python3.12编写程序

这也是本项目的规范，详见 贡献指南。

8.3 示例与说明相互配合

命令、配置和 API 行为适合用可运行的示例展示，同时保留必要的前提、风险和预期结果。只有描述而没有示例，读者往往难以验证操作是否正确。

好的写法 — 写一句引导语，紧跟一个代码块：

使用 git status 查看状态：

Bash
git status

差的写法 — 用文字描述本可以用代码展示的内容：

我们可以在终端中输入 git 加上 status 这个子命令来查看当前仓库的状态。

8.4 链接用文字，不用“这里”

Markdown
# 好
详见 [贡献指南](/zh/docs/about/contributing)

# 差
详见贡献指南, [点击这里](/zh/docs/about/contributing)

避免空洞的链接文字

“点击这里”、“这个链接”这类文字毫无信息量，读者扫一眼不知道指向什么。链接文字应该描述目标内容，让读者一眼判断是否需要点进去。

九、工具推荐

工具用途特点
VS Code源码编辑与 Markdown 预览适合与代码、配置和项目文档一起编辑
Typora所见即所得编辑器适合写长文，付费
Obsidian个人知识管理支持双向链接，适合构建知识库

TIP

在 VS Code 中打开 .md 文件，按 Ctrl + Shift + V 打开预览，或 Ctrl + K 然后 V 打开侧边预览，边写边看效果。

十、更多参考

想看更多语法示例，参考本项目的 Markdown 语法示例。想了解本项目的特定规范，参见 贡献指南。

需要编写复杂数学公式或完整排版文档时，可以继续阅读 1.9 LaTeX；遇到复杂图表，则配合 1.10 Mermaid 使用，在 Markdown 中直接画流程图、时序图。

Markdown 的核心

Markdown 的语法不多，重点在于“用结构表达内容”。写之前先想清楚文章分几节、每节写什么，再用标题、列表和图表组织内容。

十一、TODO 清单

  • 能用标题、列表、链接、图片、表格和代码块组织一篇短文
  • 所有代码块都标注了正确的语言
  • 熟记标题层级连续，链接文字能说明目标内容
  • 能根据内容重要性选择普通提示框或折叠详情块
  • 尝试在目标渲染器中预览并检查最终效果

十二、值得我们思考的问题

同一份 Markdown，在不同平台的 渲染结果 为什么会不一样？

Markdown 最初的语法说明没有覆盖所有解析细节，后来出现了多种实现。CommonMark 为核心语法提供了明确规范和测试用例，GFM 等平台扩展又在通用语法之上加入表格、任务列表等内容，因此不同渲染器仍可能产生差异。

写作时优先使用通用语法与 CommonMark 特性；确需使用平台扩展时，先确认目标平台的支持情况，或在发布前用目标环境实际渲染检查一次。

同一份 Markdown，在不同平台的 渲染样式 为什么会不一样？

Markdown 的渲染分为两步：先被解析为 HTML（决定内容的结构），再由各平台的 CSS 决定外观。解析结果由 CommonMark / GFM 等规范保证基本一致，但字体、间距、代码高亮、浅色 / 深色主题等都属于平台自己的样式，因此同一份文档在不同站点上看起来不同是正常现象。

写作时应把“语法是否被支持”和“样式如何呈现”分开判断：结构与语义用通用语法保证兼容，外观差异交给各平台主题即可；确需使用特殊组件或扩展语法时，在目标平台实际渲染检查一次。

为什么本项目中的部分语法在其他平台渲染时会显示为普通文本且样式也不同？

本项目（Neoverse-Docs）就是上述两个问题的实例：

我们在 Fumadocs 基础上扩展了 GitHub Alert 风格的提示块（[!NOTE]、[!WARNING] 等）与 [!DETAILS] 系列折叠块（FAQ、ANSWER、EXAMPLE、HINT、AI），并以液态玻璃主题、自定义代码块样式渲染。

其中 [!DETAILS] 系列由项目我们自己的 Remark 插件实现：在本站会显示为可展开的折叠卡片，而放到 GitHub 等只实现基础 GFM 的平台时，该语法不被识别，会退化为普通引用块。

[!NOTE] 这类则是 GitHub 原生语法，两端都有图标与配色，只是样式细节不同。

1.7 文本编辑

理解纯文本、字符编码与换行符，掌握 VS Code 的安装、基础操作、常用编辑技巧与正则表达式

1.9 LaTeX

认识 LaTeX 排版系统，掌握数学公式、文档结构、交叉引用与基本编译流程

本页目录

一、Markdown 是什么二、基础语法2.1 标题2.2 段落与换行2.3 强调2.4 列表2.5 链接与图片2.6 引用2.7 分隔线三、代码块3.1 行内代码3.2 代码块3.3 在代码块中显示反引号四、表格五、任务列表六、转义字符七、扩展语法7.1 GitHub Flavored Markdown（GFM）7.2 警告框（Alert / Callout）7.3 可折叠详情块7.4 数学公式八、写作规范8.1 结构清晰8.2 中英文排版8.3 示例与说明相互配合8.4 链接用文字，不用“这里”九、工具推荐十、更多参考十一、TODO 清单十二、值得我们思考的问题

讨论区

欢迎分享你的想法与建议