· 5 MIN · 参考 · markdown

博客功能速查：Markdown 写作参考

本文是一份可直接拷贝的语法清单，展示了本站支持的所有 Markdown 与扩展语法。建议在写作时打开它对照参考。

文章 frontmatter 字段

每篇文章顶部的 YAML frontmatter 支持如下字段：

字段类型默认说明
titlestring—必填。文章标题
datedate—必填。发布日期，YYYY-MM-DD
descriptionstring?—摘要，会出现在 OG meta 与 RSS
tagsstring[][]标签数组
categoriesstring[][]分类数组（保留字段，当前未单独展示）
tocbooleantrue是否生成目录
draftbooleanfalse草稿。dev 可见、prod 隐藏
keywordsstring?—SEO 关键字
seriesstring?—系列名。同 series 的文章会自动归组到 /series
seriesOrdernumber?—系列内顺序

标题层级

正文最高从 ## 开始（# 与 post-title 重复，建议不用）。当前文章里所有 ## 上面都有一道分隔线作为”小节带”。

三级标题示例

正文内容放在三级下面。

四级标题示例

四级仍然是同色系，仅字号、字重略低。

中英混排与 CJK 自动间距

中文写作时不需要手动加空格——remark-cjk-friendly 会在构建时自动给中英之间补空格。比如下面这一行原文是连写的：

使用Astro6构建，配合TailwindCSSv4和ShikiOneDarkPro主题。

它会被渲染为有正确空隙的版本。中文标点也会做行末悬挂、行首挤压（spec §P1·8）。

行内格式

加粗、斜体、删除线、行内代码、超链接。

行内数学：当 a≠0a \ne 0 时，ax2+bx+c=0ax^2 + bx + c = 0 的解是 x=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}。

列表

无序列表：

  • 第一项
  • 第二项
    • 嵌套子项
    • 又一项
  • 第三项

有序列表：

  1. 装好依赖
  2. 跑构建
  3. 部署上线

任务列表（GFM 兼容）：

  • 配置 Pagefind 搜索
  • CJK 自动间距
  • 写更多文章

引用

“克制 > 装饰。所有 border 永远只用 1px，浮件用矩形文字按钮。”

——本站设计规范

提示框（Callouts）

提示框使用 :::type 容器指令语法，类型有 note / tip / info / warn / danger。可选自定义标题写在中括号里。

代码块

行内代码：const x = 42;

带语言标签的代码块——左上角显示语言名，右上角悬停时出现”复制”按钮：

# 启动 dev 服务器
pnpm install
pnpm dev
// reading-time.ts —— CJK 友好的阅读时长估算
export function readingTime(content: string) {
  const cjk = content.match(/[一-鿿]/g)?.length ?? 0;
  const latin = content.match(/[A-Za-z0-9]+/g)?.length ?? 0;
  return Math.max(1, Math.round(cjk / 400 + latin / 220));
}
# Python 也行
def fib(n: int) -> int:
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a
// C++ 17 CTAD 示例
#include <utility>

std::pair p{1, "hello"};   // 推导为 std::pair<int, const char*>

表格

支持标准 Markdown 表格，自带 Shiki 不会改动表格样式：

功能实现方式触发
全文搜索PagefindCtrl/Cmd + K 或顶部按钮
CJK 间距remark-cjk-friendly构建时
数学公式KaTeX$...$ / $$...$$
流程图Mermaid（客户端渲染）```mermaid 代码块
图片 lightboxmedium-zoom点击 .prose img
上一篇 / 下一篇按发布时间排序文章末尾

数学公式（KaTeX）

行内：质能方程 E=mc2E = mc^2。

块级公式：

∫−∞∞e−x2 dx=π\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}

矩阵：

A=[123456789]A = \begin{bmatrix} 1 & 2 & 3 \\ 4 & 5 & 6 \\ 7 & 8 & 9 \end{bmatrix}

求和与极限：

lim⁡n→∞∑k=1n1k2=π26\lim_{n \to \infty} \sum_{k=1}^{n} \frac{1}{k^2} = \frac{\pi^2}{6}

Mermaid 图表

流程图：

flowchart LR
    A[Markdown] -->|remark/rehype| B[HTML]
    B --> C{是否含 mermaid?}
    C -->|是| D[客户端 mermaid.js<br/>转 SVG]
    C -->|否| E[直出]
    D --> F[页面渲染]
    E --> F

时序图：

sequenceDiagram
    participant U as 用户
    participant B as 浏览器
    participant P as Pagefind
    U->>B: Cmd+K
    B->>B: 打开搜索 Modal
    B->>P: 加载 /pagefind/pagefind-ui.js
    P-->>B: 返回 PagefindUI 类
    B->>B: new PagefindUI(...)
    U->>B: 输入关键字
    B->>P: search("关键字")
    P-->>B: 返回结果
    B->>U: 渲染列表

图片与 lightbox

正文中的图片自动启用 lightbox（点击放大）——下面这张图就是活样本，点击它会以遮罩方式放大居中显示，再点一次或按 Esc 关闭。

一只猫

写法就是普通的 Markdown 图片语法：

![一只猫](/cat.jpg)

如果某张图不想被放大，加 class="no-zoom" 即可（HTML 写法）：

<img src="/cat.jpg" alt="不放大的猫" class="no-zoom" />

系列文章

在 frontmatter 写 series 与 seriesOrder，本文就会出现在文章顶部的系列导航里，同时在 /series 索引中聚合：

---
series: "io_uring 系列"
seriesOrder: 2
---

本文 frontmatter 写了 series: "站点维护" 与 seriesOrder: 1，可以在文章正文上方看到一个系列导航卡。

上一篇 / 下一篇

文章末尾自动按发布日期排序展示前后导航，左侧是更早的，右侧是更新的。

全文搜索

按下 Ctrl/Cmd + K 或点击 Header 右侧”搜索”按钮，会弹出 Pagefind 模态框。索引在 pnpm build 时生成，dev 环境下没有索引，需要 pnpm preview 验证。

阅读时长与草稿标记

文章 meta 行格式为 YYYY / MM / DD · N MIN · TAGS。N MIN 是按 CJK 400 字 / 分钟、Latin 220 词 / 分钟估算的。本文没标 draft: true，所以 meta 上没有 DRAFT 角标；写草稿时把它打开即可。

视觉过渡 + 预拉取

Astro 6 的 ClientRouter 已启用，跨页面跳转有平滑动画；Header 里的导航链接 hover 时浏览器会预拉取目标页面，几乎无延迟。

到这里基本覆盖了写作时会用到的所有语法。如果未来加入新功能（脚注、视频嵌入等），再回来更新这一篇。