这是一篇博客语法速查文档。所有语法项都按”模板”和”效果”整理，写文章时可以直接复制使用。

一、常用 Markdown

标题

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

分割线

1
---

强调

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

加粗 斜体 删除线

引用

1
> 这是一级引用
2
>
3
> > 这是二级引用

这是一级引用

这是二级引用

脚注

1
这是一句带脚注的话[^1]
2


3
[^1]: 这是脚注内容

列表与任务列表

1
- 无序列表项
2
- 第二项
3


4
1. 有序列表项
5
2. 第二项
6


7
- [x] 已完成
8
- [ ] 未完成

行内代码与代码块

1
行内代码：`const title = "hello"`
2


3
```js
4
const title = "hello";
5
console.log(title);
6
```

表格

1
| 字段 | 含义 |
2
| --- | --- |
3
| title | 文章标题 |
4
| date | 发布时间 |
字段含义
title文章标题
date发布时间

链接

1
[外部链接](https://astro.build)
2
[站内链接](/about)

图片

1
<!-- public 目录（公共资源） -->
2
![封面图](/images/文章名/cover.svg)
3


4
<!-- 文章目录相对路径（文章专属截图） -->
5
![配图](images/文章名/image.png)

HTML 注释

1
这行会显示
2
<!-- 这行不会显示 -->
3
这行也会显示

二、博客扩展语法

提示块

1
:::tip[提示]
2
这里写提示内容
3
:::
4


5
:::note
6
这里写补充说明
7
:::
8


9
:::caution
10
这里写警告内容
11
:::
12


13
:::danger
14
这里写危险提示
15
:::

折叠块

1
:::collapse[点击展开]
2
这里适合放补充说明、排查过程、长日志。
3
:::
点击展开

这里适合放补充说明、排查过程、长日志。

原生 details 折叠

1
<details>
2
<summary>点击展开</summary>
3
这里是原生 HTML details 内容。
4
</details>
点击展开 这里是原生 HTML details 内容。

Remixicon 图标

1
:i{class="ri-github-fill"}
2
:i{class="ri-lightbulb-flash-line"}
3
:i{class="ri-book-open-line"}

按钮

1
:btn[打开 GitHub]{href="https://github.com"}
2


3
:::btn{href="/about"}
4
:i{class="ri-information-line"} 关于页面
5
:::

打开 GitHub

关于页面

遮掩文本

1
:spoiler[这是一段默认隐藏的内容]

这是一段默认隐藏的内容

GitHub 仓库卡片

1
::github{repo="wdxzf/wdxzf.github.io"}
wdxzf
/
wdxzf.github.io
Waiting for api.github.com...
Waiting
Waiting
Waiting

Mermaid 图表

在 frontmatter 中设置 mermaid: true，然后使用 mermaid 代码块：

1
```mermaid
2
flowchart LR
3
  A[开始] --> B[写草稿] --> C[预览] --> D[发布]
4
```
flowchart LR
  A[开始] --> B[写草稿] --> C[预览] --> D[发布]

MathJax 公式

在 frontmatter 中设置 mathjax: true，然后使用公式语法：

1
行内公式：$E = mc^2$
2


3
块公式：
4
$$
5
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
6
$$

行内公式：$E = mc^2$

块公式： $$ \sum_{i=1}^{n} i = \frac{n(n+1)}{2} $$

代码块：标题与行高亮

1
```js title="post.js" {3}
2
function publishPost() {
3
  const title = "博客语法速查文档";
4
  console.log(title);
5
}
6
```
post.js
1
function publishPost() {
2
  const title = "博客语法速查文档";
3
  console.log(title);
4
}

代码块：增删标记

1
```js title="diff-demo.js" del={2} ins={3-4}
2
function demo() {
3
  console.log("old line");
4
  const title = "new title";
5
  console.log(title);
6
}
7
```
diff-demo.js
1
function demo() {
2
  console.log("old line");
3
  const title = "new title";
4
  console.log(title);
5
}

代码块：终端样式

1
```bash
2
pnpm run validate:content
3
pnpm run build
4
```
Terminal window
1
pnpm run validate:content
2
pnpm run build

三、博客目录结构

  • 博客内容位于：src/content/blog
  • 所有 .md 文件都会被视为博客文章
  • 支持使用子目录对文章进行分类
  • 目录本身不会生成页面

子目录示例

1
src/content/blog/wsl/xxx.md
2
src/content/blog/stm32/yyy.md
3
src/content/blog/ros/zzz.md

四、Frontmatter 字段速查

字段作用说明
title标题必填
date发布时间必填，格式 YYYY-MM-DD
description摘要建议必填，不要用占位文本
lastModified最后修改时间不填时回退到文件修改时间
category分类建议 1 个主分类，写数组
tags标签写检索词，写数组
series系列名系列文章时填写
seriesOrder系列顺序系列文章时填写
draft草稿true 时生产环境不发布
sticky置顶权重数值越大越靠前
toc目录默认开启，false 关闭
comment评论区默认开启，false 关闭
donate赞赏区按文章控制
mathjax公式渲染有公式时设为 true
mermaid图表渲染有图表时设为 true
slug固定链接自定义 URL 时填写，建议英文
ogImage社交分享图封面文章建议填写

五、写作模板

最小可用模板

1
---
2
title: "文章标题"
3
description: "一句话概括本文内容"
4
date: 2026-04-14
5
category: [分类]
6
tags: [标签]
7
slug: "custom-slug"
8
---
9


10
## 一、前言

完整模板

1
---
2
title: "文章标题"
3
description: "一句话概括本文内容"
4
date: 2026-04-14
5
lastModified: 2026-04-14
6
category: [分类]
7
tags: [标签1, 标签2]
8
series: "系列名"
9
seriesOrder: 1
10
mathjax: false
11
mermaid: false
12
draft: false
13
sticky: 0
14
toc: true
15
comment: true
12 collapsed lines
16
donate: false
17
slug: "custom-slug"
18
ogImage: ""
19
---
20


21
## 一、前言
22


23
## 二、正文
24


25
:::tip[提示]
26
这里写重点内容
27
:::

六、写作时自动生效的功能

  • 图片懒加载与点击预览：图片自动懒加载，支持点击放大，能识别尺寸时自动补宽高
  • 外部链接新标签页：正文中外部链接自动加 target="_blank" 和安全属性
  • 阅读时间与字数：标题下方自动计算显示
  • 最后修改时间：lastModified 不填时自动回退到文件修改时间