Markdown 写作完全指南：从基础到扩展语法

为什么用 Markdown 写作？

Markdown 是一种轻量级标记语言，用纯文本符号表达排版意图。相比 Word 或 LaTeX，它有几个关键优势：

• 专注内容而非排版 — 写作时不打断思路去调格式
• 纯文本可迁移 — 任何编辑器都能打开，不依赖特定软件
• 版本控制友好 — Git diff 可以清楚看到内容变化
• 可扩展 — 可以嵌入 HTML、LaTeX、Mermaid 图表等

本博客使用 Astro 的 Markdown/MDX 引擎，在标准 Markdown 基础上扩展了许多功能。

基础语法速查

标题

1
# 一级标题
2
## 二级标题
3
### 三级标题
4
#### 四级标题

文字格式

1
**粗体**  *斜体*  ~~删除线~~  `行内代码`

链接与图片

1
[链接文字](https://example.com)
2
![图片描述](/path/to/image.jpg)

列表

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

1
- 项目一
2
- 项目二
3
  - 嵌套项目
4
  - 另一个嵌套

有序列表使用数字：

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

代码块语法高亮

本博客使用 Expressive Code（基于 Shiki）进行代码高亮，支持明暗双主题。

使用三个反引号包裹代码，并指定语言：

1
```python
2
def fibonacci(n: int) -> int:
3
    """计算第 n 个斐波那契数"""
4
    if n <= 1:
5
        return n
6
    a, b = 0, 1
7
    for _ in range(n - 1):
8
        a, b = b, a + b
9
    return b
10

11
for i in range(10):
12
    print(f"F({i}) = {fibonacci(i)}")
13
```

效果如下：

1
def fibonacci(n: int) -> int:
2
    """计算第 n 个斐波那契数"""
3
    if n <= 1:
4
        return n
5
    a, b = 0, 1
6
    for _ in range(n - 1):
7
        a, b = b, a + b
8
    return b
9

10
for i in range(10):
11
    print(f"F({i}) = {fibonacci(i)}")

TypeScript 示例：

1
interface BlogPost {
2
  title: string;
3
  published: Date;
4
  tags: string[];
5
  content: string;
6
}
7

8
function formatPost(post: BlogPost): string {
9
  return `[${post.published.toISOString()}] ${post.title}`;
10
}

代码块功能

• 行号：自动显示行号
• 折叠：长代码块可以折叠（点击标题栏切换）
• 复制按钮：悬停时显示复制按钮
• 自动换行：长代码行自动换行，无需横向滚动

数学公式

本博客使用 KaTeX（服务端）+ MathJax 3（客户端） 双重渲染方案。KaTeX 速度极快，MathJax 作为复杂公式的回退。

内联公式

用 $...$ 包裹：$E = mc^2$，质能方程是物理学中最著名的公式之一。

复变函数中的柯西积分公式：$f(a) = \frac{1}{2\pi i} \oint_\gamma \frac{f(z)}{z-a} dz$

块级公式

用 $$...$$ 包裹（各占一行）：

矩阵

多行公式

提示框（Admonitions）

本博客支持 5 种提示框，在标准 Markdown 之外：

1
:::note
2
这是一个普通的提示信息。
3
:::
4

5
:::tip
6
这是一个建议或技巧。
7
:::
8

9
:::important
10
这是重要信息，需要注意。
11
:::
12

13
:::caution
14
这是警告，需要谨慎。
15
:::
16

17
:::warning
18
这是严重警告，需要特别注意。
19
:::

渲染效果如下：

ⓘNOTE

这是一个普通的提示信息，用于补充说明。

⚡TIP

这是一个建议或技巧，可以帮助你更好地完成任务。

⚠IMPORTANT

这是重要信息，请务必注意。

🛠CAUTION

这是警告，操作前请仔细阅读说明。

🔥WARNING

这是严重警告，操作不当可能导致问题。

兼容 GitHub 语法

本博客也支持 GitHub 风格的提示框，会自动转换：

1
> [!NOTE]
2
> 这是一个 GitHub 风格的提示。

Mermaid 图表

使用 ```mermaid 代码块绘制流程图、时序图等：

1
```mermaid
2
graph TD
3
    A[开始] --> B{判断条件}
4
    B -->|是| C[执行操作1]
5
    B -->|否| D[执行操作2]
6
    C --> E[结束]
7
    D --> E
8
```

效果：

时序图：

主题自适应

Mermaid 图表会自动跟随网站明暗主题切换——切换到暗色模式时图表也会变为暗色配色。

表格

表格在移动端会自动变为可横向滚动，不会破坏页面布局。

引用

这是一段引用文本。可以包含粗体、斜体等格式。

嵌套引用：

外层引用

内层引用

更深层的引用

任务列表

• 搭建博客框架
• 配置主题与样式
• 添加搜索功能
• 接入评论系统
• 添加友链页面

图片增强

基础图片

自定义宽度

本博客扩展了图片语法，可以在 alt text 中指定宽度和居中：

1
![描述 w-400 center](/path/to/image.jpg)
2
![描述 w-80%](/path/to/image.jpg)

• w-400 — 宽度设为 400px
• w-80% — 宽度设为父容器的 80%
• center — 图片居中显示

Github 仓库卡片

1
:github[soren-abt/my-knowledge-base]

这会从 GitHub API 拉取仓库信息并渲染为信息卡片，包含 Stars、Forks、License、语言等信息。目前这个功能在构建时运行，所以不会影响页面加载性能。

分割线

使用 --- 创建分割线：

VSCode 写作配置

推荐在 VSCode 中安装以下插件获得更好的 Markdown 写作体验：

• MDX — 语法高亮和智能提示
• Markdown Preview Enhanced — 实时预览
• Prettier — 自动格式化
• Markdownlint — 语法规范检查

推荐设置

1
{
2
  "editor.wordWrap": "on",
3
  "markdown.preview.breaks": true,
4
  "[markdown]": {
5
    "editor.formatOnSave": true
6
  }
7
}

写作建议

1. 合理使用标题层级 — 不要跳级（如 H2 后直接用 H4），保持嵌套逻辑清晰
2. 代码块标注语言 — ```python 而不是 ```，以获得正确的语法高亮
3. 段落之间留空行 — Markdown 用空行分隔段落，单个换行符会被忽略
4. 链接使用描述性文字 — 避免 “点击这里”，用有意义的链接文字
5. 图片添加 alt 描述 — 可访问性更好，SEO 也有帮助

总结

结合 Astro 的 remark/rehype 插件管道，本博客的 Markdown 能力远超标准规范。你可以用纯文本写出包含数学公式、图表、代码高亮、提示框的丰富内容。

以上就是本博客支持的全部 Markdown 语法和扩展功能。