Markdown 完全指南

Markdown 是一种轻量级标记语言，让你可以使用易读易写的纯文本格式编写文档，然后转换成结构化的 HTML。

为什么选择 Markdown？

简单易学：语法简洁，5 分钟即可上手
纯文本：可以用任何文本编辑器编辑
跨平台：在任何操作系统上都能使用
版本控制友好：与 Git 完美配合
广泛支持：GitHub、GitLab、Notion、Obsidian 等平台都支持

基础语法

标题

使用 # 符号创建标题，# 的数量代表标题级别：

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

段落和换行

段落之间用空行分隔。如果需要在段落内换行，在行尾添加两个空格。

这是第一段。

这是第二段。

这是同一段内的
换行（注意行尾有两个空格）。

强调

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

效果：斜体、粗体、粗斜体、~~删除线~~

列表

无序列表：

- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2
- 项目 3

有序列表：

1. 第一项
2. 第二项
   1. 子项 2.1
   2. 子项 2.2
3. 第三项

链接

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

图片

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

引用

> 这是一段引用。
>
> 可以有多个段落。
>
> > 嵌套引用

效果：

这是一段引用。

代码

行内代码：

使用 `console.log()` 输出日志。

代码块：

```javascript
function hello() {
  console.log("Hello, World!");
}
```

进阶语法

表格

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 数据1 | 数据2 | 数据3 |
| 数据4 | 数据5 | 数据6 |

对齐方式：

| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| 左     | 中       | 右     |

任务列表

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

效果：

已完成的任务
未完成的任务

脚注

这是一段文字[^1]。

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

水平分隔线

---
或
***
或
___

转义字符

使用反斜杠 \ 转义特殊字符：

\* 不是斜体
\# 不是标题
\[不是链接\]

扩展语法

数学公式（LaTeX）

行内公式： $E = mc^2$

块级公式：

$$
\int_{a}^{b} f(x) dx
$$

图表代码块（Mermaid / PlantUML）

知识库站点会自动识别 mermaid、plantuml、puml 代码块，并在文章页渲染为图形。JavaScript 禁用或渲染失败时，页面会保留原始代码块，保证内容仍然可读。

Mermaid 适合流程图、时序图、脑图、甘特图等轻量图表：

```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
    C --> D
```

PlantUML 适合 UML 类图、组件图、部署图和复杂时序图：

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml
```

IntelliJ IDEA 本地预览

IDEA 默认 Markdown 预览通常不会直接渲染这些图表，需要额外配置：

确认 Settings -> Plugins 中已启用 bundled Markdown 插件。
Mermaid：安装 JetBrains Marketplace 的 Mermaid 插件，然后重新打开 Markdown 预览。
PlantUML：安装 PlantUML integration / plantuml4idea 插件。
PlantUML 的部分图形需要 Graphviz。macOS 可运行 brew install graphviz，安装后重启 IDEA。
如果 IDEA 预览和网站渲染不一致，优先用 mermaid.live 或 PlantUML 官方服务检查语法。

高亮

==高亮文本==

上标和下标

H~2~O（下标）
X^2^（上标）

最佳实践

1. 文档结构

使用一个 # 作为文档标题
使用 ## 作为主要章节
保持标题层级的连贯性

2. 代码块

始终指定代码语言以获得语法高亮
使用有意义的代码示例
添加注释说明关键部分

3. 链接管理

使用引用式链接保持文档整洁：

这是 [Google][1] 和 [GitHub][2]。

[1]: https://google.com
[2]: https://github.com

4. 图片优化

使用描述性的替代文本
考虑图片大小和加载速度
使用相对路径引用本地图片

5. 可读性

段落之间留空行
列表项保持简洁
使用引用突出重要信息

常用工具

编辑器

VS Code：配合 Markdown All in One 插件
Typora：所见即所得的 Markdown 编辑器
Obsidian：知识管理工具
Notion：协作文档平台

在线工具

StackEdit：在线 Markdown 编辑器
Dillinger：云端 Markdown 编辑器
HackMD：协作式 Markdown 笔记

转换工具

Pandoc：文档格式转换的瑞士军刀
Marked：Markdown 预览工具
mdBook：从 Markdown 生成书籍

实战案例

技术文档

# API 文档

## 用户认证

### POST /api/auth/login

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| email | string | 是 | 用户邮箱 |
| password | string | 是 | 用户密码 |

**响应示例**：

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com"
  }
}


### README 文件

```markdown
# 项目名称

简短的项目描述。

## 特性

- 特性 1
- 特性 2
- 特性 3

## 快速开始

```bash
npm install
npm run dev

文档

查看完整文档。

贡献

欢迎提交 Pull Request！

许可证

MIT


## 总结

Markdown 是现代开发者必备的技能之一。掌握 Markdown 可以让你：

- 高效编写技术文档
- 在 GitHub 上创建专业的 README
- 快速记录笔记和想法
- 生成静态网站和博客

开始使用 Markdown，让你的文档更加专业和易读！

## 参考资源

- [Markdown 官方文档](https://daringfireball.net/projects/markdown/)
- [GitHub Flavored Markdown](https://github.github.com/gfm/)
- [CommonMark 规范](https://commonmark.org/)
- [Markdown Guide](https://www.markdownguide.org/)