Markdown 文档实践笔记

一、为什么用 Markdown

Markdown 是一种轻量级标记语言，用简单的符号就能表达标题、列表、链接等格式。它的优点很明显：

• 纯文本格式，任何编辑器都能打开，方便版本管理；
• 语法简单，几分钟就能上手，专注内容而不是排版；
• 可以方便地转换成 HTML、PDF 等格式。

二、常用语法速查

标题与段落

# 一级标题
## 二级标题
### 三级标题

正文段落之间用一个空行分隔。

列表

- 无序列表项一
- 无序列表项二

1. 有序列表项一
2. 有序列表项二

链接与图片

[链接文字](https://example.com)
![图片描述](assets/images/demo.png)

代码块

用三个反引号包裹代码，并标注语言名称可以获得语法高亮：

```bash
echo "hello world"
```

表格

| 命令 | 说明       |
| ---- | ---------- |
| ls   | 列出文件   |
| cd   | 切换目录   |

引用与强调

> 这是一段引用文字

**加粗文字**  *斜体文字*  ~~删除线~~  `行内代码`

三、我的写作实践习惯

1. 文件命名统一：笔记文件用小写英文加连字符命名，例如 nginx-config.md，避免中文文件名在不同系统间的兼容问题；
2. 目录结构清晰：按主题建文件夹，每个主题下再按日期或内容拆分文件；
3. 善用标题层级：一篇文章控制在三级标题以内，层级太深说明该拆分文件了；
4. 代码块标注语言：既方便阅读，也方便以后用工具渲染出高亮效果；
5. 先写结论再写过程：技术笔记先写怎么解决，再写排查过程，方便日后快速查阅。

四、常用工具

• 编辑器：VS Code 自带 Markdown 预览，配合快捷键使用非常顺手；
• 转换导出：pandoc 可以把 Markdown 转换成 HTML、Word、PDF 等格式；
• 图床管理：本地笔记图片统一放在 assets/images 目录，用相对路径引用。

小结

Markdown 的核心是“内容优先”。语法本身不难，关键是养成统一的写作规范，这样笔记积累多了以后依然整洁、可维护。