Markdown:用符号写文档

Markdown 是什么

Markdown 是一种用纯文本写格式化文档的标记语言。它用简单的符号表示标题、加粗、列表、链接等格式,写起来快,读起来也清楚。

程序员写文档几乎都用 Markdown:README、技术博客、API 文档、笔记。本文站的所有文章,就是用 Markdown 写的。

基本语法

标题

用 `#` 表示,数量代表层级:

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

段落和换行

空一行表示新段落。段内换行:行尾加两个空格,或 `<br>`。

强调

**加粗**
*斜体*
***加粗斜体***
~~删除线~~

效果:**加粗** *斜体* ***加粗斜体*** ~~删除线~~

列表

无序列表用 `-` 或 `*`:

- 第一项
- 第二项
  - 嵌套项

有序列表用数字:

1. 第一步
2. 第二步

代码

行内代码用反引号:

用 `npm install` 安装依赖。

代码块用三个反引号,可标语言:

`markdown
```js
const x = 1;
```
`

引用

用 `>`:

> 这是一段引用。
> 第二行。

链接和图片

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

表格

| 姓名 | 年龄 |
|------|------|
| 小明 | 25   |
| 小红 | 23   |

分隔线

三个或更多 `-`:

---

为什么用 Markdown

写得快

不用鼠标点格式,键盘搞定一切。手不离键盘,心不离内容。

可读性好

即使不渲染,纯文本也能看懂结构。`# 标题` 比 `<h1>标题</h1>` 直观。

版本控制友好

纯文本,Git 能 diff,改了哪行一目了然。Word 文档改了什么看不出来。

跨平台

任何编辑器都能写,任何平台都能渲染。GitHub、Notion、飞书、博客系统都支持。

可转换

能转成 HTML、PDF、Word。写一次,多平台发布。

在哪写 Markdown

• **VS Code**:装插件预览,边写边看效果。
• **Typora**:专门的 Markdown 编辑器,所见即所得。
• **GitHub**:README 自动渲染。
• **Notion / 飞书**:支持 Markdown 语法输入。

本站怎么用 Markdown

本站的文章存在数据库里,字段叫 `content_md`,就是 Markdown 格式。你在文章详情页看到的内容,是 Markdown 渲染成 HTML 的结果:

• `## 标题` 显示为大标题。
• `` `代码` `` 显示为行内代码块。
• `- 列表` 显示为项目符号。

写文章时用 Markdown,存进数据库,前端渲染时转成 HTML。这是技术文档的标准流程。

小白记住

• `#` 是标题,`**` 是加粗,反引号是代码。
• 纯文本写,渲染后显示格式。
• 程序员的标准文档格式,所有平台都支持。

学会 Markdown,你就能写技术文档、做笔记、写博客。本站的文章也是用 Markdown 写的,你看的这段就是。