README、技术博客、接口文档、会议纪要……如今几乎所有技术写作都离不开 Markdown。它用极简的符号标记格式,让纯文本同时具备"易读"和"易渲染"两种属性:在编辑器里是清爽的源码,发布后是排版精美的页面。本文带你掌握最常用的语法,并给出写作规范。

1. 标题与段落

用 # 的个数表示标题级别,从一级到六级;# 后要加一个空格。段落之间用空行分隔,换行不会产生新段落(很多新手在这里踩坑):

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

这是第一段,后面跟两个空格加回车可以强制换行。
这是第二段,需要空行分隔。

2. 强调与列表

列表分有序和无序两种,嵌套时缩进两个空格:

- 无序列表项
- 另一个列表项
  - 嵌套项(缩进两格)

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

3. 链接与图片

链接和图片语法几乎一样,图片多一个感叹号:

[CodeLab 首页](https://example.com)

![替代文字](https://example.com/logo.png "可选标题")
💡 图片务必写"替代文字":屏幕阅读器依赖它,图片加载失败时它也会显示出来,这是可访问性的基本要求。

4. 代码:行内与代码块

行内代码用反引号包裹,代码块用三个反引号包裹并标注语言,渲染时会带语法高亮:

这是行内代码 `git commit -m "feat: init"`。

```python
def greet(name):
    return f"Hello, {name}!"
```

5. 表格与引用

| 语法 | 用途 | 难度 |
| ---- | ---- | ---- |
| 标题 | 组织结构 | 简单 |
| 列表 | 罗列要点 | 简单 |
| 表格 | 对比数据 | 中等 |

> 引用别人的话或注意事项,用大于号开头。

表格分隔行中的 : 可以控制对齐,如 | :---: | 表示居中对齐。注意表格列数要一致,否则渲染会错位。

6. 写作规范建议

  1. 文件名用英文小写 + 连字符,如 docker-guide.md,避免中文和空格
  2. 中英文之间加空格,如"使用 Docker 部署",阅读更舒适
  3. 一个主题一个文件,长文档用 ## 拆成可跳转的章节
  4. 统一使用 UTF-8 编码,避免乱码
  5. 善用任务列表:- [ ] 待办 / - [x] 完成
# 学习计划
- [x] 掌握基础语法
- [x] 学会插入代码块
- [ ] 用 Markdown 重写一篇旧博客
💡 学习建议:把 Markdown 当成日常笔记工具用起来,写周报、记笔记、写 README 都用它;再配合 Git 管理版本,你就拥有了一个可检索、可追溯的个人知识库。