每条格式:引用块里是写法(照着抄),下面不引用的是实际渲染效果。这篇文章自己就用了文中的目录、代码块和 Callout 语法。
Callout 提示块
基本形式
写法:一行
> [!类型]开头,下面每行都带>:> [!tip] 这是一个提示 > 提示内容写在这里,可以多行。
实际渲染:
提示内容写在这里,可以多行。
全部类型
写法:把类型换掉即可,标题可写可不写(不写就显示类型名):
> [!note] 笔记 > [!info] 信息 > [!todo] 待办
实际渲染(一批):
默认的蓝色笔记块。
info 和 note 是近亲,浅蓝色。
用来标记要做的事。
绿色,表示完成或正确。
黄色,提出问题。
橙色,需要注意。
红色,高风险操作。
记录问题复现。
紫色,示例代码或用法。
灰色,引用别人说的话。
青色,也可以写 summary / tldr。
别名
写法:部分类型有别名,效果一样:
hint/important→ tip、check/done→ success、help/faq→ question、caution/attention→ warning、error→ danger、cite→ quote、fail/missing→ failure。> [!hint] 别名演示 > 这其实是一个 tip。
实际渲染:
这其实是一个 tip。
可折叠
写法:类型后面加
-默认收起、加+默认展开,点标题折叠:> [!warning]- 默认收起的警告 > 点标题展开我。 > [!info]+ 默认展开的信息 > 点标题收起我。
实际渲染(点一下试试):
默认收起的警告
点标题展开我。
默认展开的信息
点标题收起我。
内容里可以写 Markdown
写法:提示块内部照常支持加粗、链接、列表、代码等:
> [!example] 语法演示 > 行内 **加粗**、`code`、[链接](/p/hugo-astro-paper-syntax/) 都行。 > > - 列表项一 > - 列表项二
实际渲染:
行内 加粗、code、链接 都行。
- 列表项一
- 列表项二
不带 [!类型] 开头的引用块还是原来的引用样式,旧文章的引用都不用改。
代码块文件名徽章
写法:语言后面跟
{file="文件名"}(注意要花括号):```js {file="app.js"} const a = 1; ```
实际渲染(块上方有带绿点的文件名标签):
const a = 1;代码块行标记
写法:行尾加
// [!code ++]标新增、// [!code --]标删除、// [!code highlight]高亮该行:```js const kept = "原样"; const added = "新增的行"; // [!code ++] const removed = "删除的行"; // [!code --] const focused = "高亮的行"; // [!code highlight] ```
实际渲染(绿底 + 为新增,红底 - 为删除,灰底为高亮):
const kept = "原样";
const added = "新增的行";
const removed = "删除的行";
const focused = "高亮的行";写法:整行注释形式一次标记接下来 N 行(
[!code --:3]表示后面 3 行):```css /* [!code --:3] */ .old-a { color: red; } .old-b { color: red; } .old-c { color: red; } .new-a { color: green; } ```
实际渲染(标记行本身不显示,后面 3 行整体删除态):
.old-a { color: red; }
.old-b { color: red; }
.old-c { color: red; }
.new-a { color: green; }frontmatter 特殊字段
写法(都是可选字段):
--- title: "文章标题" featured: true # 出现在首页「Featured」区块 lastmod: 2026-11-20T11:30:00+08:00 # 晚于 date 时,日期行显示 "Updated:" hideToc: true # 本文不显示目录(默认自动生成) slug: "自定义url" # /p/<slug>/ draft: true # 草稿,构建时不发布 ---
实际效果:首页 Featured 区块现在放的是 PlanningToDo;带 lastmod 的文章日期行会出现 “Updated:"(本文就有);hideToc: true 单篇关闭自动目录。
自动行为(无需写法)
文章有标题就在标题下方生成缩进目录,点击跳转;hideToc: true 可单篇关闭。本文顶部就有一份。
全站自动启用 View Transitions:首页点标题进来时标题会「飞」过来,导航栏宽度也会平滑拉宽到文章列——离开文章又缩回去。纯 CSS 实现,无需写任何东西。
点导航栏搜索图标或按 Cmd+K / Ctrl+K,输入即搜全文;索引由部署流程自动生成。
frontmatter 的 tags 每一项自动生成 /tags/<标签>/ 聚合页(文章多时自动分页);导航「Tags」页可看全部标签。RSS 在 /rss.xml(首页标题旁的图标即入口)。