🔧 CodeKit
EN

Markdown 完全指南：从入门到精通

CodeKit
markdown文档gfm

Markdown 完全指南：从入门到精通

Markdown 是一种轻量级标记语言，由 John Gruber 于 2004 年创建，目标是让写作者能够以易读易写的纯文本格式编写文档，并轻松转换为结构化的 HTML。如今，Markdown 已成为技术文档、博客、README 文件和笔记应用的事实标准。本文将全面介绍 Markdown 的核心语法、GitHub Flavored Markdown（GFM）扩展以及文档编写的最佳实践。

一、Markdown 基础语法

1.1 标题

使用 # 号表示标题层级，从一级到六级：

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

建议在 # 后加一个空格，这是大多数解析器的要求，也符合 CommonMark 规范。

1.2 段落与换行

Markdown 中段落由一个或多个空行分隔。若想在段落内换行，可在行末加两个空格或使用 <br> 标签：

这是第一行（行末加两个空格）
这是第二行

这是一个新段落。

1.3 强调

*斜体文本* 或 _斜体文本_
**粗体文本** 或 __粗体文本__
***粗斜体文本*** 或 ___粗斜体文本_
~~删除线文本~~

推荐统一使用 * 号，避免与下划线命名冲突。

1.4 列表

无序列表使用 -、* 或 +：

- 项目一
- 项目二
  - 子项目 2.1
  - 子项目 2.2
- 项目三

有序列表使用数字加点：

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

1.5 链接与图片

[链接文本](https://example.com)
[带标题的链接](https://example.com "鼠标悬停提示")

![替代文本](image.png)
![带标题的图片](image.png "图片标题")

引用式链接可以让正文更简洁：

[CodeKit][1] 是一款优秀的在线工具集。

[1]: https://codekit.app "CodeKit 官网"

1.6 引用

> 这是一段引用文本。
>
> > 引用可以嵌套。
>
> 引用中可以包含 **格式** 和 `代码`。

1.7 分隔线

三个或更多的 *、- 或 _：

---

***

___

二、代码块

2.1 行内代码

使用反引号包裹：

使用 `console.log()` 输出调试信息。

若代码中包含反引号，使用双反引号包裹：

`` 代码中有 ` 反引号 ``

2.2 围栏代码块

使用三个反引号并指定语言实现语法高亮：

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}

console.log(greet('CodeKit'));
```

常用语言标识：javascript、python、java、go、rust、sql、bash、json、yaml、typescript。

2.3 代码块中的缩进

代码块内保持原始缩进，不要额外添加：

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)
```

三、GFM 扩展语法

GitHub Flavored Markdown 在标准 Markdown 基础上增加了多项实用功能，已成为最广泛使用的 Markdown 变体。

3.1 表格

| 功能 | 语法 | 说明 |
| --- | :---: | ---: |
| 左对齐 | `:---` | 默认对齐 |
| 居中 | `:---:` | 居中对齐 |
| 右对齐 | `---:` | 右对齐 |

渲染效果：

功能语法说明
左对齐:---默认对齐
居中:---:居中对齐
右对齐---:右对齐

3.2 任务列表

- [x] 完成 Markdown 基础语法学习
- [x] 掌握 GFM 扩展
- [ ] 编写项目文档
- [ ] 代码审查

任务列表在项目管理、TODO 追踪中非常实用，GitHub 还支持直接在页面上勾选。

3.3 删除线

~~这段内容已过时~~

3.4 自动链接

GFM 会自动将 URL 转换为可点击链接：

访问 https://codekit.app 查看更多工具。

3.5 脚注

部分 GFM 实现支持脚注语法：

这是一个需要注释的文本[^1]。

[^1]: 这是脚注内容。

四、最佳实践

4.1 保持结构清晰

  • 每个文档只包含一个一级标题
  • 标题层级不要跳跃（如从 ## 直接到 ####）
  • 每个章节保持合理的长度，避免过长的段落

4.2 善用代码块

  • 始终指定代码块的语言，以启用语法高亮
  • 代码示例应简洁且可运行
  • 复杂示例添加注释说明关键步骤

4.3 链接管理

  • 优先使用引用式链接，保持正文整洁
  • 确保链接可访问，避免死链
  • 图片始终提供替代文本，增强可访问性

4.4 格式一致性

  • 列表标记统一使用 -
  • 强调统一使用 *
  • 代码块统一使用围栏语法而非缩进语法
  • 文件末尾保留一个空行

4.5 文档模板

为团队项目建立统一的文档模板：

# 项目名称

> 简短描述

## 快速开始

```bash
npm install project-name
```

## 使用方法

### 基本用法

## 配置

## 常见问题

## 贡献指南

## 许可证

4.6 实用技巧

  1. 使用 HTML 补充格式：Markdown 不支持的格式（如 <details> 折叠块）可嵌入 HTML
  2. 转义特殊字符：使用反斜杠 \ 转义 Markdown 语法字符，如 \*不是斜体\*
  3. 嵌入数学公式：许多平台支持 LaTeX 语法，如 $E = mc^2$
  4. Mermaid 图表：部分平台支持在代码块中使用 Mermaid 绘制流程图、时序图

五、在线预览与验证

编写 Markdown 时，实时预览能极大提升效率。CodeKit Markdown 预览器 提供了在线实时预览功能，支持 GFM 扩展语法、代码高亮和多种导出格式。无论是快速验证语法还是编写完整文档，都能得心应手。

总结

Markdown 以其简洁的语法和强大的表现力，成为现代文档编写的首选工具。掌握基础语法是起点，善用 GFM 扩展能让文档更专业，而遵循最佳实践则能确保团队协作中的文档质量。从 README 到技术博客，从 API 文档到知识库，Markdown 的应用场景无处不在。开始用 Markdown 写作吧，你会发现纯文本也能如此优雅。