内容编写指南

如何使用各 Markdown 插件编写和更新站点内容

内容编写指南

本指南介绍站点支持的所有 Markdown 扩展语法，供编写和更新内容时参考。

1. 文件基础

文件位置

所有内容文件放在 src/content/docs/ 下，支持 .md 和 .mdx 两种格式。.mdx 可以在 Markdown 中直接使用 JSX 组件。

Frontmatter

每个文件顶部需要 YAML frontmatter：

---
title: "页面标题"
description: "页面描述（可选，用于 SEO）"
date: "2026-01-01"        # 可选
subject: "数学"            # 可选
weight: 10                 # 可选，用于排序
---

目录结构示例

src/content/docs/
├── math/
│   ├── index.md
│   ├── foundations/
│   │   └── sets.md
│   └── calculus/
│       └── limits.md
└── writing-guide.mdx      # 本文件

2. 基础 Markdown 与 GFM

由 remark-gfm 提供 GitHub 风格 Markdown 支持。

表格

| 运算 | 符号 | 示例 |
|------|------|------|
| 并集 | A∪B | {1,2,3} |
| 交集 | A∩B | {2} |

删除线与任务列表

~~删除的文本~~

- [x] 已完成
- [ ] 待办

自动链接

裸 URL 会自动转为链接：https://example.com → https://example.com

3. 数学公式

由 remark-math + rehype-katex 提供，使用 KaTeX 渲染。

行内公式

用 $...$ 包裹：

欧拉公式 $e^{i\pi} + 1 = 0$ 是数学中最美的等式。

渲染效果：欧拉公式 $e^{i\pi} + 1 = 0$ 是数学中最美的等式。

块级公式

用 $$...$$ 包裹，单独成段：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

渲染效果：

\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}

4. 提示框（GitHub Alerts）

由 remark-github-alerts 提供，使用 GFM 风格语法。在引用标记后加 [!类型]：

> [!note]
> 这是一条笔记提示。

> [!tip]
> 这是一条提示建议。

> [!warning]
> 这是一条警告信息。

> [!important]
> 这是一条重要说明。

> [!caution]
> 这是一条注意事项，请格外小心。

渲染效果：

笔记

这是一条笔记提示。

提示

这是一条提示建议。

警告

这是一条警告信息。

重要

这是一条重要说明。

注意

这是一条注意事项，请格外小心。

5. 定理环境

由 remark-theorem 提供，用于数学证明的严谨排版。使用 :::类型{label="标签" name="名称"} 语法。

可用类型

类型	用途
`theorem`	定理
`lemma`	引理
`proof`	证明
`axm`	公理
`defi`	定义
`exam`	例
`prop`	命题
`rema`	注
`corr`	推论

基本用法

:::theorem{label="de-morgan" name="德摩根律"}
对于任意集合 $A$ 和 $B$：

$$\overline{A \cap B} = \bar{A} \cup \bar{B}$$
:::

:::proof
设 $x \in \overline{A \cap B}$，则 $x \notin A \cap B$...
:::

渲染效果：

定理1　示例定理：

设 $f: A \to B$ 为双射，则 $f^{-1}: B \to A$ 存在且唯一。

证明：

因 $f$ 为双射，故 $f$ 既是单射又是满射…

交叉引用

在任意位置引用已定义的定理：

由 :ref[guide-thm] 可知逆映射存在。

其证明见 :proofref[guide-thm]。

渲染效果：由定理1 可知逆映射存在。其证明见定理1的证明。

定义与例

定义1　连续函数：

设 $f: \mathbb{R} \to \mathbb{R}$ ，若 $\lim_{x \to a} f(x) = f(a)$ 对所有 $a$ 成立，则称 $f$ 连续。

例：

函数 $f(x) = x^2$ 在 $\mathbb{R}$ 上连续。

6. 标题锚点

由 rehype-slug + rehype-autolink-headings 提供，自动为每个标题生成 ID 和锚链接。

标题自动获得 id 属性（如 #section-name）
鼠标悬停标题时显示 # 锚链接，点击可跳转到该位置
无需手动操作，所有 ##、### 等标题均自动处理

7. 外部链接

由 rehype-external-links 提供，自动为外部链接添加安全属性。

[华为云](https://www.huaweicloud.com)

所有指向站外的链接自动添加 target="_blank" 和 rel="nofollow noreferrer noopener"，无需手动处理。站内链接保持默认行为。

8. 原始 HTML

由 rehype-raw 提供，可在 Markdown 中直接写 HTML：

<div class="highlight-box">
  <p>这是一段 <strong>自定义 HTML</strong> 内容。</p>
</div>

渲染效果：

这是一段 自定义 HTML 内容。

9. 图片

由 rehype-unwrap-images 提供，图片不再被 <p> 标签包裹，便于直接控制布局。

![替代文本](/images/example.png)

将图片放在 public/images/ 目录下，引用时用 /images/文件名。

10. 中英文混排

由 remark-cjk-friendly 提供，自动处理中文与英文/数字之间的间距问题。

直接写 中文English混排 即可，插件自动在 CJK 与拉丁字符间添加适当间距，无需手动加空格。

11. 代码高亮

由 Astro 内置 Shiki 提供，支持语法高亮。

行内代码

使用 `const` 声明变量。

代码块

```typescript
function greet(name: string): string {
  return `Hello, ${name}!`;
}
```

渲染效果：

function greet(name: string): string {
  return `Hello, ${name}!`;
}

标题与行高亮

```typescript title="utils.ts" {2}
function greet(name: string): string {
  return `Hello, ${name}!`; // 这行高亮
}
```

12. Mermaid 图表

由 astro-mermaid 提供，用 mermaid 代码块绘制流程图：

```mermaid
graph LR
  A[开始] --> B{条件?}
  B -->|是| C[执行]
  B -->|否| D[跳过]
  C --> E[结束]
  D --> E
```

13. MDX 特性

使用 .mdx 扩展名时，可在 Markdown 中导入和使用 Astro 组件：

import MyComponent from '../../components/MyComponent.astro';

<MyComponent prop="value" />

速查表

语法	插件	示例
表格/删除线/任务列表	remark-gfm	`\|表\|`、`~~删除~~`、`- [x]`
行内公式	remark-math	$E=mc^2$
块级公式	remark-math	`$$...$$`
提示框	remark-github-alerts	`> [!note]`
定理	remark-theorem	`:::theorem{label="x"}`
定理引用	remark-theorem	`:ref[x]`
标题锚点	rehype-slug	自动生成
外部链接	rehype-external-links	自动处理
原始 HTML	rehype-raw	`<div>...</div>`
图片解包	rehype-unwrap-images	`![]()`
CJK 间距	remark-cjk-friendly	自动处理
代码高亮	Shiki (内置)	```ts
流程图	astro-mermaid	```mermaid