XiaoMai

XiaoMai 写作与使用指南

Wed, 26 Aug 2026 00:00:00 GMT

欢迎使用 XiaoMai（小麦）——一款富有表现力、受动漫风格启发的博客主题，围绕 Astro 7、Svelte 5 与 Material 3 Expressive（M3E） 设计系统打造。

本指南将带你了解文章创建、frontmatter 规范、目录结构，以及全套内置的 Markdown 与 MDX 扩展。

:::tip XiaoMai 优先在服务器端渲染内容（SSR-first）。在站内导航时，Swup 会无缝替换主容器，同时保留外层应用外壳与持续的背景音乐播放。 :::

1. 创建新文章

你可以使用内置 CLI 命令快速生成带有标准 frontmatter 的新文章：

# 创建单文件文章
pnpm new-post my-first-post

# 或在子目录中创建文章
pnpm new-post guides/getting-started

新创建的文件会放置在 src/content/posts/ 目录下。

2. Frontmatter 规范

每篇 Markdown（.md）或 MDX（.mdx）文章都以一段 YAML frontmatter 开头，用于定义其元数据。

示例

---
title: "Exploring Material 3 Expressive Design"
published: 2026-08-26
updated: 2026-08-27
publishedAt: 2026-08-26T10:00:00+08:00
updatedAt: 2026-08-27T09:30:00+08:00
pinned: true
description: "A deep dive into dynamic HCT color science and fluid transitions in XiaoMai."
image: "./cover.webp"
tags: [M3E, Design, Frontend]
category: Guides
draft: false
comment: true
---

支持的 Frontmatter 字段

字段	类型	必填	说明
`title`	`string`	是	文章的主标题。
`published`	`Date`	是	发布日期，格式为 `YYYY-MM-DD`。
`publishedAt`	`Date`	否	精确发布时刻，用于排序同一天发布的文章。它必须落在 `published` 所配置的站点时区内。
`updated`	`Date`	否	最后更新日期。提供后会显示更新提示徽标。
`updatedAt`	`Date`	否	供订阅源与机器可读元数据使用的精确更新时刻。必须与 `updated` 配对。
`pinned`	`boolean`	否	将文章置顶到文章列表顶部（默认：`false`）。
`description`	`string`	否	文章摘要，显示在文章卡片、搜索结果与 OpenGraph 元数据中。
`image`	`string`	否	封面图路径。支持相对路径（`./cover.webp`）、公共路径（`/images/cover.jpg`）或远程 URL。
`tags`	`string[]`	否	用于分类筛选与标签云的标签名数组。
`category`	`string`	否	用于分类索引的主分类名称。
`draft`	`boolean`	否	标记为draft。draft文章在生产构建（`pnpm build`）期间会被隐藏。
`comment`	`boolean`	否	为该篇特定文章开关评论区（默认：`true`）。
`lang`	`string`	否	语言代码（例如 `en`、`zh_CN`、`ja`），当与站点默认值不同时使用。

3. 文章加密

XiaoMai 提供客户端文章加密。对于私人日记或受限文章，可在 frontmatter 中指定密码：

---
title: "Private Research Notes"
published: 2026-08-26
encrypted: true
password: "your-secret-passphrase"
passwordHint: "Favorite anime character"
hideHomeContent: true
---

encrypted：设为 true 以启用加密；
password：解锁文章所需的口令字符串或数字；
passwordHint：可选提示，显示在密码输入表单上方；
hideHomeContent：在首页隐藏字数统计与内容预览，防止数据泄露。

4. 组织文章文件

XiaoMai 同时支持基于文件夹的就近存放与单文件布局：

文件夹结构（本地资源推荐）

将文章与其媒体资源就近存放，可让资源管理变得简单：

src/content/posts/
├── my-great-post/
│   ├── index.md           <-- 文章内容
│   ├── cover.webp         <-- 封面图（image: "./cover.webp"）
│   └── diagram.png        <-- Markdown 中引用的内联插图

单文件结构（轻量随笔）

src/content/posts/
├── hello-world.md
└── quick-thoughts.md

5. 丰富的 Markdown 与 MDX 扩展

XiaoMai 开箱即用地内置了现代化的 Markdown 扩展：

5.1 admonitions（Admonitions）

使用容器指令来呈现备注、提示、警告与警示：

:::tip
使用admonitions容器来突出关键要点或最佳实践。
:::

:::warning
使用警告容器来提示潜在的陷阱或破坏性变更。
:::
:::note
使用备注容器来记录补充性的背景信息或补充说明。
:::
:::info
使用信息容器来提供中性的上下文说明，帮助理解周围内容。
:::
:::important
使用重要容器来强调必须留意的关键事项或约束条件。
:::
:::caution
使用警示容器来标注高风险、不可逆或需要格外小心的操作。
:::
:::details
使用详情容器来收纳可折叠的可选内容，默认收起。
:::

:::tip 使用admonitions容器来突出关键要点或最佳实践。 :::

:::warning 使用警告容器来提示潜在的陷阱或破坏性变更。 :::

:::note 使用备注容器来记录补充性的背景信息或补充说明。 ::: :::info 使用信息容器来提供中性的上下文说明，帮助理解周围内容。 ::: :::important 使用重要容器来强调必须留意的关键事项或约束条件。 ::: :::caution 使用警示容器来标注高风险、不可逆或需要格外小心的操作。 ::: :::details 使用详情容器来收纳可折叠的可选内容，默认收起。 :::

5.2 GitHub 仓库卡片

使用指令语法嵌入实时、样式精美的 GitHub 仓库卡片：

::github{repo="GrowWheat/XiaoMai"}

::github{repo="GrowWheat/XiaoMai"}

5.3 Expressive Code 代码块

增强型代码块具备语法高亮、文件名徽标、行号以及选择性行高亮等特性：

// Dynamic HCT color token derivation
import { argbFromHex, themeFromSourceColor } from "@material/material-color-utilities";

const theme = themeFromSourceColor(argbFromHex("#f472b6"));
console.log("Primary color token:", theme.schemes.light.primary);

5.4 数学排版（KaTeX）

直接在 Markdown 中渲染优雅的 LaTeX 数学公式：

行内公式： $E = mc^2$ 或欧拉公式 $e^{i\pi} + 1 = 0$。
块级公式：

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

5.5 Mermaid 图表

使用纯文本创建流程图、时序图与架构图：

sequenceDiagram
    autonumber
    actor Visitor as 访客
    participant Page as XiaoMai 页面
    participant Swup as Swup 容器
    participant Audio as 常驻外壳

    Visitor->>Page: 点击导航链接
    Page->>Swup: 触发无缝过渡
    Swup->>Page: 替换 #swup-container
    Note over Audio: 背景音乐持续播放
    Page-->>Visitor: 新页面已渲染

5.6 图片画廊与 Fancybox 灯箱

图片会自动与 Fancybox 集成，支持无损缩放、平移手势与全屏预览：

![Cover preview](./cover.jpeg)

6. 后续步骤与自定义

站点配置：了解 src/config/siteConfig.ts 与 src/config/README.md 中的全局设置。
设计令牌：在 DESIGN.md 与 docs/m3e-standard.md 中探索令牌与调色板。
反馈与社区：在 GitHub Issues 上分享你的想法与问题。

🔒 密码保护与文章加密演示

Thu, 20 Aug 2026 00:00:00 GMT

🔒 本文已加密保护，请访问博客网站输入密码阅读全文。

XiaoMai Markdown 增强功能

Wed, 19 Aug 2026 00:00:00 GMT

XiaoMai 提供了一系列主题专属的 Markdown 扩展与自定义语法容器。基于我们原生的 unified AST 处理管线构建，所有扩展在站点构建时即渲染为无障碍、语义化的 HTML，具备零客户端 JavaScript 水合开销与 100% M3E 设计令牌对齐。

文件树

文件树可将多层项目结构、源码层级与终端目录输出，转换为紧凑、可交互的树状视图，带有自动扩展名图标、差异高亮与可折叠分支。

1. 嵌套列表语法（`:::file-tree`）

当直接以 Markdown 嵌套列表的形式书写文件层级时，使用 :::file-tree 块指令。

:::file-tree{title="XiaoMai source tree"}
- src
  - components/
    - ++ Navigation.svelte # added component
    - -- Button.astro # removed component
  - content
    - posts/
      - markdown-增强功能.md
  - layouts/
    - PostLayout.astro
  - plugins
    - markdown/
      - rehype-file-tree.mjs
  - styles
    - markdown/
      - trees.css
  - **content.config.ts** # important file
- public/
  - favicon.svg
- package.json
:::

:::file-tree{title="XiaoMai 源码树"}

src
- components/
  - ++ Navigation.svelte # added component
  - -- Button.astro # removed component
- content
  - posts/
    - markdown-增强功能.md
- layouts/
  - PostLayout.astro
- plugins
  - markdown/
    - rehype-file-tree.mjs
- styles
  - markdown/
    - trees.css
- content.config.ts # important file
public/
- favicon.svg
package.json :::

写作规则与标记

差异状态：在条目前加 ++（绿色背景与徽标）或 --（红色背景与删除线）以突出改动。
注释：# 之后的任意文本会渲染为弱化的、右对齐行内注释。
强调：用 **粗体** 包裹名称，让关键文件获得醒目的视觉权重。
可折叠文件夹：由嵌套列表项推断出的目录默认展开。添加末尾斜杠（例如 components/）可创建一个折叠目录，读者可通过点击或键盘导航展开。

2. 终端输出语法（```file-tree）

当你已经有用 tree 等命令行工具生成的目录树文本时，可直接粘贴进 file-tree 围栏代码块。Unicode 分支字符（├──、└──、│）与 ASCII 分支都会被自动解析。

```file-tree title="Build output" icon="simple"
dist
├── _astro/
│   ├── index.css
│   └── page.js
└── favicon.ico
```

dist
├── _astro/
│   ├── index.css
│   └── page.js
└── favicon.ico

配置选项

title="string"：为树设置自定义标题与无障碍标签。
icon="colored" | "simple"：在多彩扩展图标（colored，默认）与极简单色图标（simple）之间选择。

代码树

交互式代码树将左侧的多级文件层级导航面板与右侧的即时代码面板切换配对。它们为多文件示例、模块或整个目录的导读提供了类似 IDE 的阅读体验。

1. 容器语法（`:::code-tree`）

在 :::code-tree 块指令中组合多个围栏代码块。每个代码块通过 title="path/to/file" 指定其路径。

:::code-tree{title="XiaoMai Component Demo" height="380px" entry="src/Button.svelte"}
```svelte title="src/Button.svelte"
<script lang="ts">
  let { label = "Click me" } = $props();
</script>

<button class="m3-btn">{label}</button>
```

```stylus title="src/styles/button.styl"
.m3-btn
  background: var(--primary)
  color: var(--on-primary)
  border-radius: var(--shape-corner-m)
```

```json title="package.json"
{
  "name": "button-demo",
  "version": "1.0.0"
}
```
:::

:::code-tree{title="XiaoMai 组件演示" height="380px" entry="src/Button.svelte"}

<script lang="ts">
  let { label = "Click me" } = $props();
</script>

<button class="m3-btn">{label}</button>

.m3-btn
  background: var(--primary)
  color: var(--on-primary)
  border-radius: var(--shape-corner-m)

{
  "name": "button-demo",
  "version": "1.0.0"
}

:::

配置与标记

title="string"：为代码树设置标题与无障碍标签。
height="string"：设置桌面视图的高度（默认 420px，例如 380px、26rem）。
entry="filepath"：指定首次加载时处于激活状态的文件。
icon="colored" | "simple"：在彩色或极简单色文件图标之间切换。
:active：在任意围栏代码块上放置 :active，将其指定为默认激活标签页。

2. 本地目录自动导入（`@[code-tree]`）

直接指向工作区中的任意本地目录路径，即可在构建时自动扫描并生成交互式代码树，无需手动复制文件内容。

@[code-tree title="代码树工具" entry="code-tree.ts"](/src/utils)

@code-tree title="站点配置" entry="siteConfig.ts"

图片画廊网格：语法与完整示例

Tue, 15 Sep 2026 00:00:00 GMT

:::grid 是博客的图片画廊容器指令。它把普通 Markdown 图片排列成统一宽高比、响应式的网格，并自动启用灯箱查看。可用于文章配图、截图、作品集或小型相册。

同一画廊中的图片采用相同的卡片比例。默认情况下，居中对齐裁剪会填满每张卡片，并保持每一行整齐；点击图片会在灯箱中打开完整的原图。每个画廊拥有独立的灯箱分组，不会与文章中的其他图片混在一起。

本文既是功能文档，也是视觉测试页。请在桌面、平板和手机宽度下查看示例，然后点击任意图片以验证灯箱分组是否正确。

最简语法

直接在 :::grid 与结束标记 ::: 之间书写 Markdown 图片：

:::grid
![Image description](./image-1.webp)

![Image description](./image-2.webp)
:::

每张图片必须独占一个段落，图片之间需保留空行。画廊中只放图片；段落、列表和代码块请写在容器之外。

以下是最简语法的效果。不带参数时，网格默认使用三列、16/10 比例和 cover 填充模式。

:::grid

:::

参数一览

将所有参数以花括号写在起始指令之后：:::grid{parameter="value"}。

参数	允许值	默认值	用途
`columns`	`1` 到 `6` 之间的整数	`3`	桌面端每行显示的列数。非法值回退到 `3`。
`aspect`	正比例，例如 `16/9`、`3/4` 或 `1/1`	`16/10`	显示的卡片比例，而非原始图片比例。
`fit`	`cover`、`contain`	`cover`	图片适配模式。`cover` 裁剪填充；`contain` 保留完整图片，可能留下空白。

完整示例：

:::grid{columns="3" aspect="16/9" fit="cover"}
![First image](./image-1.webp "Optional caption")

![Second image](./image-2.webp "Optional caption")

![Third image](./image-3.webp "Optional caption")
:::

以下结果使用了上面的三列横向语法。请对比卡片比例、列数，以及标题优先于 alt 文本作为图注的方式：

:::grid{columns="3" aspect="16/9" fit="cover"}

:::

图注与 Alt 文本

图片的 alt 文本既作为无障碍替代文本，也作为默认图注。当图片带有可选的标题（title）时，将以该标题作为图注：

![Text used for accessibility](./image.webp "Caption shown below the image")

在同一行中，图注会统一对齐到每张卡片的底部。折行的图注不会使其他卡片浮动到不同高度。诸如 3:4 和 16:9 这样的比例文字可直接写在正文、标题和 alt 文本中，无需转义。

以下示例演示了默认 alt 文本图注、显式标题图注，以及较长图注的底部对齐：

:::grid{columns="3" aspect="1/1"}

:::

布局与裁剪

桌面布局采用 columns 指定的列数。低于 768px 时，网格最多两列；低于 480px 时，切换为一列。卡片外层固定 aspect 比例并裁剪圆角，图片则填满卡片，不受主题默认图片边距影响。

选择 cover：推荐的默认模式。图片从中心裁剪以填满卡片，使画廊看起来整齐一致。
选择 contain：显示完整原图，不做裁剪。当其比例与卡片不同时，主题背景会保持可见；适用于不能裁剪的图片。
若要保留完整图片且不出现空白，请将 aspect 设置为接近原图比例，或将图片单独放入一个网格。

以下示例将相同的纵向图片分别放入 16/9 卡片，使用 cover 与 contain。前者裁剪图片；后者保留完整图片并留出背景空间。

:::grid{columns="3" aspect="16/9" fit="cover"}
![Image description](./image-1.webp "Optional caption")

![Image description](./image-2.webp "Optional caption")
:::

:::grid{columns="3" aspect="16/9" fit="contain"}
![Image description](./image-1.webp "Optional caption")

![Image description](./image-2.webp "Optional caption")
:::

:::grid{columns="3" aspect="16/9" fit="cover"}

:::

:::grid{columns="3" aspect="16/9" fit="contain"}

:::

默认配置

不带属性时，默认是三列、16/10 比例和 cover 裁剪。这三张纵向图片用于验证默认裁剪与图注。

:::grid
![Image description](./image-1.webp)

![Image description](./image-2.webp)

![Image description](./image-3.webp)
:::

:::grid

:::

三列纵向图片：3:4

使用 aspect="3/4" 时，三张纵向图片会填满比例一致的竖卡片。若原图比例不同，cover 会从中心裁掉边缘。

:::grid{columns="3" aspect="3/4"}
![Portrait image description](./portrait-1.webp)

![Portrait image description](./portrait-2.webp)

![Portrait image description](./portrait-3.webp)
:::

:::grid{columns="3" aspect="3/4"}

:::

三列横向图片：16:9

这组示例演示了三列布局中常见的视频封面比例。当横向图片接近卡片比例时，裁剪量最小。

:::grid{columns="3" aspect="16/9"}
![Landscape image description](./landscape-1.webp)

![Landscape image description](./landscape-2.webp)

![Landscape image description](./landscape-3.webp)
:::

:::grid{columns="3" aspect="16/9"}

:::

两列方形图片：1:1

需要较大预览卡片时，两列效果很好。第三张图片会移到下一行。最后一行保持网格轨道宽度，而不会拉伸图片填满整行。

:::grid{columns="2" aspect="1/1"}
![Square image description](./square-1.webp)

![Square image description](./square-2.webp)

![Square image description](./square-3.webp)
:::

:::grid{columns="2" aspect="1/1"}

:::

四列与 `contain`

fit="contain" 不会对原图做裁剪。当图片比例与卡片比例不同，主题背景会保持可见。这是有意为之，而非布局问题。它同时验证了四列网格与独立灯箱分组不会互相干扰。

:::grid{columns="4" aspect="16/9" fit="contain"}
![Image description](./image-1.webp)

![Image description](./image-2.webp)

![Image description](./image-3.webp)
:::

:::grid{columns="4" aspect="16/9" fit="contain"}

:::

单列细节图片

当图片需要较大阅读尺寸时，单列正合适。它在桌面、平板和手机上都保持单列，灯箱中仍可查看原图。

:::grid{columns="1" aspect="16/9"}
![Image description](./detail.webp)
:::

:::grid{columns="1" aspect="16/9"} :::

稀疏五列行

五列用于验证更高的支持列数。由于只有三张图片，最后一行保持左对齐，而不会拉伸图片。

:::grid{columns="5" aspect="1/1"}
![Thumbnail description](./thumb-1.webp)

![Thumbnail description](./thumb-2.webp)

![Thumbnail description](./thumb-3.webp)
:::

:::grid{columns="5" aspect="1/1"}

:::

六列中的混合图片

六列是当前的最大值。混合横向与纵向图片，用于验证 cover 裁剪、窄卡片上的图注，以及密集的桌面布局。就文章正文可读性而言，通常两到四列更合适。

:::grid{columns="6" aspect="1/1"}
![Image description](./image-1.webp)

![Image description](./image-2.webp)

![Image description](./image-3.webp)

![Image description](./image-4.webp)

![Image description](./image-5.webp)

![Image description](./image-6.webp)
:::

:::grid{columns="6" aspect="1/1"}

:::

四列方形图片：1:1

四张比例相同的方形图片是典型的四列布局。桌面端在一行内显示全部四张；平板折叠为两列，手机折叠为一列。

:::grid{columns="4" aspect="1/1"}
![Square image description](./square-1.webp)

![Square image description](./square-2.webp)

![Square image description](./square-3.webp)

![Square image description](./square-4.webp)
:::

:::grid{columns="4" aspect="1/1"}

:::

六列横向图片：16:9

六列横向布局适合缩略图预览、作品集和截图索引。即使原图比例略有差异，cover 也能一致地填满每张 16/9 卡片。

:::grid{columns="6" aspect="16/9"}
![Landscape image description](./landscape-1.webp)

![Landscape image description](./landscape-2.webp)

![Landscape image description](./landscape-3.webp)

![Landscape image description](./landscape-4.webp)

![Landscape image description](./landscape-5.webp)

![Landscape image description](./landscape-6.webp)
:::

:::grid{columns="6" aspect="16/9"}

:::

三列纵向图片：3:4

这一组六张纵向图片演示了人物、海报或手机截图的常见布局。图片组成两行三列，图注对齐到底部。

:::grid{columns="3" aspect="3/4"}
![Portrait image description](./portrait-1.webp)

![Portrait image description](./portrait-2.webp)

![Portrait image description](./portrait-3.webp)

![Portrait image description](./portrait-4.webp)

![Portrait image description](./portrait-5.webp)

![Portrait image description](./portrait-6.webp)
:::

:::grid{columns="3" aspect="3/4"}

:::

边缘敏感内容：`cover` 与灯箱

这些图片在边缘附近包含重要文字或细节。cover 能保持网格整齐，但可能裁掉这些边缘；点击图片可在灯箱中查看未裁剪的原图。对于边缘敏感图片，请使用清晰的图注，或改用下方的 contain。

:::grid{columns="3" aspect="16/9" fit="cover"}
![Edge-critical content](./critical-1.webp "Open the lightbox to view the complete edge content")

![Edge-critical content](./critical-2.webp "Open the lightbox to view the complete edge content")

![Edge-critical content](./critical-3.webp "Open the lightbox to view the complete edge content")
:::

:::grid{columns="3" aspect="16/9" fit="cover"}

:::

极端比例与 `contain`

对于横幅、长截图及其他极端图片比例，contain 会显示完整原图。与 cover 不同，它可能留下主题背景空间，但绝不会裁剪内容。

:::grid{columns="3" aspect="16/9" fit="contain"}
![Complete screenshot description](./wide-1.webp)

![Complete screenshot description](./wide-2.webp)

![Complete screenshot description](./wide-3.webp)
:::

:::grid{columns="3" aspect="16/9" fit="contain"}

:::

透明图片

透明图片会露出卡片的主题背景。这个单列 contain 示例便于检查透明区域、原图边缘与灯箱行为。

:::grid{columns="1" aspect="16/9" fit="contain"}
![Transparent image description](./transparent.webp)
:::

:::grid{columns="1" aspect="16/9" fit="contain"} :::

灯箱导航

点击网格中任意图片即可打开 Fancybox 灯箱。在其中可以缩放、旋转、进入全屏、查看缩略图，并使用方向键导航。导航仅限于当前的 :::grid 容器：例如，点击"16:9 测试图片一"只会打开该节中另外两张横向图片。

同一文章中的普通 Markdown 图片仍会被单独处理；它们不会被加入任何网格画廊。

检查清单

每个网格中的图片尺寸一致，图注显示在卡片下方。
图片在悬停时轻微缩放；点击后可缩放、旋转，并用键盘导航。
点击"16:9 测试图片一"时，灯箱仅能浏览该节中另外两张横向图片。
低于 768px 时，网格最多两列；低于 480px 时，为一列。
"四列与 contain"中的纵向图片完整可见，留有空白，未被裁剪。
五列与六列网格在宽屏上保持指定列数，随后按响应式规则折叠为两列或一列。

Expressive Code 示例

Thu, 10 Sep 2026 00:00:00 GMT

这里我们将了解使用 Expressive Code 时代码块的外观。所提供的示例基于官方文档，如需更多细节可参阅。

Expressive Code

语法高亮

常规语法高亮

console.log('This code is syntax highlighted!')

渲染 ANSI 转义序列

ANSI colors:
- Regular: [31mRed[0m [32mGreen[0m [33mYellow[0m [34mBlue[0m [35mMagenta[0m [36mCyan[0m
- Bold:    [1;31mRed[0m [1;32mGreen[0m [1;33mYellow[0m [1;34mBlue[0m [1;35mMagenta[0m [1;36mCyan[0m
- Dimmed:  [2;31mRed[0m [2;32mGreen[0m [2;33mYellow[0m [2;34mBlue[0m [2;35mMagenta[0m [2;36mCyan[0m

256 colors (showing colors 160-177):
[38;5;160m160 [38;5;161m161 [38;5;162m162 [38;5;163m163 [38;5;164m164 [38;5;165m165[0m
[38;5;166m166 [38;5;167m167 [38;5;168m168 [38;5;169m169 [38;5;170m170 [38;5;171m171[0m
[38;5;172m172 [38;5;173m173 [38;5;174m174 [38;5;175m175 [38;5;176m176 [38;5;177m177[0m

Full RGB colors:
[38;2;34;139;34mForestGreen - RGB(34, 139, 34)[0m

Text formatting: [1mBold[0m [2mDimmed[0m [3mItalic[0m [4mUnderline[0m

编辑器与终端边框

代码编辑器边框

console.log('Title attribute example')

<!-- src/content/index.html -->
<div>File name comment example</div>

终端边框

echo "This terminal frame has no title"

Write-Output "This one has a title!"

覆盖边框类型

echo "Look ma, no frame!"

# Without overriding, this would be a terminal frame
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

文本与行标记

标记整行与行范围

// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"

选择行标记类型（mark、ins、del）

function demo() {
  console.log('this line is marked as deleted')
  // This line and the next one are marked as inserted
  console.log('this is the second inserted line')

  return 'this line uses the neutral default marker type'
}

为行标记添加标签

// labeled-line-markers.jsx
<button
  role="button"
  {...props}
  value={value}
  className={buttonClassName}
  disabled={disabled}
  active={active}
>
  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

在独立行上添加长标签

// labeled-line-markers.jsx
<button
  role="button"
  {...props}

  value={value}
  className={buttonClassName}

  disabled={disabled}
  active={active}
>

  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

使用类 diff 语法

+this line will be marked as inserted
-this line will be marked as deleted
this is a regular line

--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+this is an actual diff file
-all contents will remain unmodified
 no whitespace will be removed either

将语法高亮与类 diff 语法结合

  function thisIsJavaScript() {
    // This entire block gets highlighted as JavaScript,
    // and we can still add diff markers to it!
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }

标记行内的个别文本

function demo() {
  // Mark any given text inside lines
  return 'Multiple matches of the given text are supported';
}

正则表达式

console.log('The words yes and yep will be marked.')

转义正斜杠

echo "Test" > /home/test.txt

选择行内标记类型（mark、ins、del）

function demo() {
  console.log('These are inserted and deleted marker types');
  // The return statement uses the default marker type
  return true;
}

自动换行

为单个代码块配置自动换行

// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

配置折行缩进

// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

可折叠区块

// All this boilerplate setup code will be collapsed
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// This part of the code will be visible by default
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // You can have multiple collapsed sections
  const a = 1
  const b = 2
  const c = a + b

  // This will remain visible
  console.log(`Calculation result: ${a} + ${b} = ${c}`)
  return c
}

// All this code until the end of the block will be collapsed again
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })

行号

为单个代码块显示行号

// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')

// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

更改起始行号

console.log('Greetings from line 5!')
console.log('I am on line 6')

Mermaid 图表画廊

Wed, 02 Sep 2026 00:00:00 GMT

Mermaid 能将 Markdown 中的文字描述转换为图表。下面的示例借助 XiaoMai 的内容工作流，演示技术文章与项目笔记中常用的图表类型。

流程图

流程图用于描述一个过程，包括判断分支以及回到较早步骤的路径。

flowchart TD
    accTitle: 文章发布工作流
    accDescr: 文章经过撰写、校验、预览与构建后发布。校验失败会退回修订。
    Draft[撰写 Markdown] --> Check{校验是否通过？}
    Check -->|否| Revise[修订文章]
    Revise --> Check
    Check -->|是| Preview[本地预览]
    Preview --> Build[构建静态页面]
    Build --> Publish[发布]

时序图

时序图按时间顺序呈现参与者之间的协作。本例跟踪一次从请求到 Mermaid 渲染的 Swup 导航。

sequenceDiagram
    accTitle: 站内导航后的图表渲染
    accDescr: 读者发起导航，Swup 替换文章内容，Mermaid 渲染器在新页面上增强图表。
    actor Reader
    participant Browser
    participant Swup
    participant Content as 文章区域
    participant Renderer as Mermaid 渲染器
    Reader->>Browser: 打开另一篇文章
    Browser->>Swup: 发起站内导航
    Swup->>Content: 替换页面内容
    Swup-->>Renderer: Emit content:replace
    Renderer->>Content: 查找 Mermaid 容器
    Renderer-->>Browser: 插入主题化 SVG

实体关系图

实体关系图用于建模结构化数据，以及作者、文章、标签与评论之间的关联。

erDiagram
    accTitle: 博客内容关系
    accDescr: 作者撰写文章，文章收到评论，连接记录将文章关联到多个标签。
    AUTHOR ||--o{ POST : 写入
    POST ||--o{ COMMENT : 收到
    POST ||--o{ POST_TAG : 归类于
    TAG ||--o{ POST_TAG : 分组
    AUTHOR {
        string id PK
        string display_name
    }
    POST {
        string slug PK
        string title
        datetime published_at
        string author_id FK
    }
    COMMENT {
        string id PK
        string post_slug FK
        string body
    }
    TAG {
        string id PK
        string label
    }
    POST_TAG {
        string post_slug FK
        string tag_id FK
    }

类图

类图用于表达软件设计中的职责、公共方法以及依赖方向。

classDiagram
    accTitle: Markdown 渲染模块
    accDescr: 内容管线使用 Mermaid 插件生成回退标记，随后客户端渲染器将其增强为 SVG。
    class ContentPipeline {
        +render(markdown)
        +collectMetadata()
    }
    class MermaidPlugin {
        +transform(codeFence)
        +createFallback()
    }
    class DiagramRenderer {
        +initialize()
        +renderAll()
        +refreshTheme()
    }
    class ThemeTokens {
        +primary
        +surface
        +outline
    }
    ContentPipeline --> MermaidPlugin : 使用
    DiagramRenderer --> MermaidPlugin : 增强输出
    DiagramRenderer --> ThemeTokens : 读取

状态图

状态图展示对象的生命周期，以及推动其在各状态间跃迁的事件。

stateDiagram-v2
    accTitle: 文章生命周期
    accDescr: 文章从draft经评审到发布，可能退回修订，最终归档。
    [*] --> Draft
    Draft --> InReview : 提交
    InReview --> Draft : 请求修改
    InReview --> Published : 批准
    Published --> Draft : 撤回
    Published --> Archived : 归档
    Archived --> [*]

XY 图表

XY 图表结合柱状与折线，在同一坐标轴上比较数值与趋势。

xychart-beta
    accTitle: 六周内容表现
    accDescr: 柱形展示归一化的每周发布量，折线展示归一化的阅读完成度。
    title "六周内容表现"
    x-axis "周" [1, 2, 3, 4, 5, 6]
    y-axis "相对得分" 0 --> 100
    bar [36, 52, 44, 68, 76, 84]
    line [48, 55, 62, 61, 73, 81]

饼图

饼图以紧凑方式比较各分类在整体中所占的比重。

pie showData
    accTitle: 文章主题占比
    accDescr: 工程占四成，设计系统占两成五，其余由指南与随笔分摊。
    title 文章主题占比
    "工程" : 40
    "设计系统" : 25
    "指南" : 20
    "随笔" : 15

甘特图

甘特图沿日历时间线排布任务、依赖关系与里程碑。

gantt
    accTitle: 主题发布计划
    accDescr: 发布计划从需求与交互设计，经组件开发、测试，直至发布。
    title 主题发布计划
    dateFormat YYYY-MM-DD
    axisFormat %m/%d
    section 设计
    Confirm requirements :done, brief, 2024-05-06, 2d
    Refine interactions :done, interaction, after brief, 3d
    section 实现
    Develop components :active, components, after interaction, 6d
    Write examples :examples, after interaction, 4d
    section 验证
    Automated tests :tests, after components, 3d
    Release :milestone, release, after tests, 0d

思维导图

思维导图将一个中心主题展开为相关领域与支撑概念。

mindmap
  root((XiaoMai))
    Content experience
      Markdown
      Search
      Diagrams
    Interface system
      M3E tokens
      Responsive layout
      Color schemes
    Engineering quality
      Astro Check
      Playwright
      Accessibility

时间线

时间线用于概括重要事件或阶段，无需给出精确的日历时长。

timeline
    title Mermaid 支持演进
    管线设计 : 检测 Mermaid 围栏
                    : 保留源码回退
    客户端增强 : 按需加载运行时
                       : 应用主题令牌
    可靠性 : 支持 Swup 导航
                : 校验响应式与无障碍输出

用户旅程图

用户旅程图结合任务各阶段中的操作、参与者与体验评分。

journey
    accTitle: 读者理解技术文章
    accDescr: 读者发现文章，将正文与图表结合以理解内容，随后探索相关主题。
    title 读者理解技术文章
    section 发现
      Browse the article list: 4: Reader
      Choose a topic: 5: Reader
    section 理解
      Read the article: 4: Reader
      Inspect a relationship diagram: 5: Reader
    section 续读
      Open a related article: 4: Reader
      Bookmark the page: 3: Reader

Git 图

Git 图展示功能分支在合并回主线之前的工作推进过程。

gitGraph
    accTitle: Mermaid 特性分支历史
    accDescr: 特性分支在合并回主分支发布之前，新增渲染器与测试。
    commit id: "base"
    branch mermaid
    checkout mermaid
    commit id: "add-renderer"
    commit id: "add-tests"
    checkout main
    merge mermaid id: "merge-mermaid"
    commit id: "release"

看板

看板按工作流状态对任务分组，便于快速浏览当前进度。

kanban
  backlog[待办]
    docs[撰写作者文档]
    examples[扩充示例数据]
  active[进行中]
    themes[验证主题适配]
  complete[已完成]
    fallback[源码回退]
    rendering[客户端渲染]

桑基图

桑基图用连线宽度表示流量或其他数量在节点之间的流动。

sankey-beta
Landing,Reading,720
Discovery,Reading,430
Reading,Explore,360
Reading,Topic,210
Reading,External,140

每个示例都使用标准的 mermaid 代码围栏。服务端会保留可读的源码标记，浏览器则将其增强为遵循当前主题的 SVG。当主题切换或 Swup 导航到本文时，图表会重新渲染。

Markdown 示例

Tue, 01 Sep 2026 00:00:00 GMT

一级标题

段落之间用一个空行分隔。

第二段。斜体、粗体和 等宽字体。无序列表看起来像这样：

这个
那个
另一个

注意——先不论星号——真正的正文内容是从第 4 列开始的。

引用块是这样写的。

它们可以跨多个段落，只要你愿意。

用三个连字符表示破折号（em-dash）。用两个连字符表示范围（例如，“全部在第 12--14 章”）。三个点 … 会被转换为省略号。支持 Unicode。☺

二级标题

下面是一个有序列表：

第一项
第二项
第三项

再次注意，真正的正文是从第 4 列开始的（距左侧 4 个字符）。这里是一个代码示例：

# 让我重申一下……
for i in 1 .. 10 { do-something(i) }

正如你可能猜到的，缩进 4 个空格即可。顺便说一句，如果不想缩进代码块，你也可以使用围栏代码块：

define foobar() {
    print "Welcome to flavor country!";
}

（这样复制粘贴更方便）。你还可以可选地标记该围栏块，让 Pandoc 对其进行语法高亮：

import time
# 快，数到十！
for i in range(10):
    #（但别太快）
    time.sleep(0.5)
    print i

三级标题

现在是一个嵌套列表：

首先，准备这些食材：
- 胡萝卜
- 芹菜
- 扁豆
烧一些水。

把一切都倒进锅里，然后按这个步骤来：

 find wooden spoon
 uncover pot
 stir
 cover pot
 balance wooden spoon precariously on pot handle
 wait 10 minutes
 goto first step (or shut off burner when done)

别碰木勺，否则它会掉下来。

注意，文本始终对齐在 4 个空格的缩进处（包括上面续写第 3 项的最后一行）。

这里有一个指向某个网站的链接，一个指向本地文档的链接，以及一个指向当前文档中某个小节标题的链接。这里还有一个脚注 ^1。

表格可以这样写：

尺码材质颜色

9 皮革棕色 10 麻布帆布原色 11 玻璃透明

Table: 鞋子、它们的尺码以及材质

（以上是表格的标题。）Pandoc 还支持多行表格：

关键词文字

红日落、苹果，以及其他红色或偏红的事物。

绿树叶、青草、青蛙，以及那些不那么容易拥有的事物。

下面是一条水平分隔线。

这是一个定义列表：

apples : 适合做苹果酱。 oranges : 柑橘类！ tomatoes : tomatoe 里没有字母“e”。

再次，文本缩进 4 个空格。（在每个术语/定义之间加一个空行，可以让内容更舒展。）

这是一个“行块”：

| 第一行 | 第二行 | 第三行

图片可以这样指定：

行内数学公式这样写：$\omega = d\phi / dt$。展示型数学公式应单独占一行，并用双美元符号包裹：

$$I = \int \rho R^{2} dV$$

$$ \begin{equation*} \pi =3.1415926535 ;8979323846;2643383279;5028841971;6939937510;5820974944 ;5923078164;0628620899;8628034825;3421170679;\ldots \end{equation*} $$

注意，你可以对想原样显示的任意标点字符加反斜杠转义，例如：`foo`、*bar* 等。

在文章中嵌入视频

Tue, 01 Sep 2026 00:00:00 GMT

只需从 YouTube 或其他平台复制嵌入代码，然后粘贴到 Markdown 文件中即可。

---
title: Include Video in the Post
published: 2026-09-01
// ...
---

<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

Bilibili

::bilibili{bvid="BV1yvBEBREfA" title="Bilibili 视频" p=1 preload="auto"}

Bilibili

::bilibili{bvid="BV1twbK6MEXn" title="Bilibili 视频" p=1 preload="auto"}

ArtPlayer

::artplayer{src="https://www.pexels.com/download/video/38538991/" title="Sintel 预告片" preload="auto"}

Audio Reader：日式动漫神秘语音

Sat, 29 Aug 2026 00:00:00 GMT

这些简短的日文语音片段，仿佛是从某个动漫场景的边缘拾来的：一声戏谑的呼唤、一句明亮的问候、一阵轻笑，还有几句来路不明的台词。它们是情绪样本而非对话脚本，所以让声音本身去承载含义吧。

Audio Reader 会让它们保持安静，直到你选择收听。每个发音按钮只有在被按下后才会加载并播放其片段。

:audio-reader[Clip title]{src="/assets/audio/filename.wav"}

片段列表

Baka（笨蛋）：:audio-reader[バカ]{src="/assets/audio/Baka.wav"}
Ciallo：:audio-reader[Ciallo！！]{src="/assets/audio/Ciallo.wav"}
Ehe（轻笑）：:audio-reader[玩笑般的语气]{src="/assets/audio/Ehe.wav"}
Imoi（土味）：:audio-reader[イモい]{src="/assets/audio/Imoi.wav"}
Zako（杂鱼）：:audio-reader[雑魚じゃん、雑魚雑魚]{src="/assets/audio/Zako.wav"}

src 必须使用站点根路径或 HTTPS URL，且指令标签不能为空。无效或不完整的指令会保持为普通 Markdown，不会加载 Audio Reader 资源。

Markdown 剧透

Fri, 28 Aug 2026 00:00:00 GMT

剧透用于隐藏一个简短的答案或情节细节，同时不将其从文档中移除。悬停、聚焦或激活原生控件即可揭示内容。

行内细节

答案是 :spoiler[42]，而这句话在其周围保持为普通 Markdown。

剧透可以包含 行内代码 以及 :spoiler[一条带强调的更长细节]。

编写语法

The answer is :spoiler[42].

生成的 HTML 使用一个带有 aria-expanded 状态的原生按钮。即使没有 JavaScript，悬停和聚焦仍能揭示文字；可选的运行时额外提供点击与键盘切换。

Markdown 文件包含

Fri, 28 Aug 2026 00:00:00 GMT

XiaoMai 可以包含一个本地 Markdown 文件，或其中一段安全的片段。

完整文件与行范围形式同样受支持：

<!-- @include: src/content/snippets/include-example.md -->
<!-- @include: src/content/snippets/include-example.md{1-4} -->
<!-- @include: src/content/snippets/include-example.md{5-} -->
<!-- @include: src/content/snippets/include-example.md{-4} -->

位于围栏代码内部的包含注释会保持原样。

Markdown 标记高亮

Fri, 28 Aug 2026 00:00:00 GMT

标记高亮用于突出某个特定短语，而不会把周围的段落变成一个独立组件。它们在构建时渲染为原生的 <mark> 元素，并继承当前活动的 M3E 配色系统。

默认强调

当强调应由文章的主色承担时，使用 ==text==。这对于 ==读者应当记住的一个决定== 很有用，同时他们可以继续阅读普通段落。

标记中可以包含 ==嵌套的 Markdown 强调==，当短语需要更强的层级时。

语义化颜色

当含义需要不同的色调角色时，使用后缀。可用的变体有 primary、secondary、tertiary、error 和 tip。

==主色将短语连接到当前主题=={.primary}
==次色让一个支撑性的区分保持低调=={.secondary}
==第三色添加一种独立的编辑信号=={.tertiary}
==错误色标识需要修正的状况=={.error}
==提示色突出实用建议=={.tip}

编写语法

==Primary marker==

==Secondary marker=={.secondary}
==Tertiary marker=={.tertiary}
==Error marker=={.error}
==Tip marker=={.tip}

诸如 ==literal marker syntax== 这样的行内代码以及围栏示例会保持原样，因此文档可以解释该语法而不触发它。

Markdown 缩写

Fri, 28 Aug 2026 00:00:00 GMT

缩写让技术写作保持紧凑，同时为需要完整术语的读者保留其全称。被定义的术语会渲染为原生的 abbr 元素，其含义可在悬停时查看，也能被辅助技术读取。

在语境中

SSR 优先（SSR-first）的输出会在 JavaScript 运行前就让初始文档可见。在衡量其阅读体验时，LCP 和 CLS 能揭示首屏可见内容是否足够快且稳定。

缩写也可以出现在 SSR 这类普通 Markdown 旁边，但诸如 SSR 这样的字面代码以及像 LCP 文档这样的链接不会被改动。

定义术语

将定义放在同一篇 Markdown 文档的任意位置。它们不会作为可见段落渲染，只有该文章中匹配的术语才会获得语义化的缩写处理。

*[SSR]: Server-Side Rendering
*[LCP]: Largest Contentful Paint
*[CLS]: Cumulative Layout Shift

SSR makes an HTML response available before client code runs.

*[SSR]: 服务端渲染（Server-Side Rendering） *[LCP]: 最大内容绘制（Largest Contentful Paint） *[CLS]: 累积布局偏移（Cumulative Layout Shift）

编写边界

术语必须以字母或数字开头，可包含字母、数字、句点、下划线、加号和连字符。每个定义仅适用于当前文章；无效或重复的定义会保持为普通 Markdown，而不会静默替换另一个术语。

Markdown 选项组

Fri, 28 Aug 2026 00:00:00 GMT

选项组把等价的操作说明放在一起，而无需重复周围的解释。每个选项都接受完整的块级 Markdown，而所选的值还能与同一页面上的另一个组同步。

选择包管理器

使用 @tab:active 选择初始选项。# 后面的后缀提供一个稳定值，而不改变可见标题。

::: tabs#package-manager

@tab npm

使用 npm 安装该包：

npm install astro

@tab:active pnpm#pnpm

使用 pnpm 安装该包：

pnpm.cmd add astro

@tab Bun#bun

使用 Bun 安装该包：

bun add astro

:::

运行项目

这个组共享 package-manager 这个 id。在上面选择一个选项会更新下方匹配的命令，并在下次访问时记住该选择。

::: tabs#package-manager

@tab npm

npm run dev

@tab pnpm

pnpm.cmd dev

@tab Bun#bun

bun run dev

:::

多种备选方案

较长的选项行保持在一行内，并在窄屏时于自身导航区域内滚动。

::: tabs

@tab 本地工作站

开发某个功能时，使用本地工具链。

@tab 托管预览环境

发布一个临时预览供审阅。

@tab 持续集成

针对每一次变更运行确定性校验。

@tab 生产部署

将经验证的产物提升到生产环境。

@tab 离线恢复流程

当网络不可用时，从本地产物恢复。

:::

编写语法

::: tabs#package-manager

@tab npm

Use npm instructions here.

@tab:active **pnpm**#pnpm

Use pnpm instructions here.

:::

每个组至少需要两个 @tab 区块，且每个区块都需要有与标记之间以空行分隔的正文内容。无效或不完整的组会作为普通 Markdown 保持可读。

Markdown collapse-panels

Fri, 28 Aug 2026 00:00:00 GMT

collapse-panels把相关的可选细节放在一个紧凑的组里。标题与正文保留行内和块级 Markdown，而原生的折叠语义让每个面板都无需客户端 JavaScript 即可使用。

独立面板

默认情况下，各项独立展开。在标题前加 :+ 可让该项初始展开，或加 :- 在组使用 expand 时保持关闭。

::: collapse

包要求

使用 Node.js 22 或更高版本，并在安装包之前启用 Corepack。
:+ 安装依赖

从仓库根目录运行工作区的包命令。
```
pnpm.cmd install
```
校验命令

在构建生产输出之前检查内容管线。
- pnpm.cmd check:manifest
- npx.cmd astro check :::

手风琴模式

当只应保留一个展开项时，添加 accordion。浏览器会直接对原生折叠元素分组，因此打开另一项会在无需注水的情况下关闭前一项。

::: collapse accordion expand

expand 在这里有什么作用？

当没有任何项带有 :+ 标记时，它会初始展开第一项。
标题可以包含 Markdown 吗？

可以。标题支持行内强调和 代码，而面板正文支持完整的块级 Markdown。
在窄屏上会发生什么？

内容内边距会变紧凑，长文本会换行，嵌入的代码保留自身的水平滚动区域。 :::

编写语法

::: collapse accordion
- :+ First title

  First panel content.

- Second title with `code`

  Second panel content.
:::

容器必须恰好包含一个顶层无序列表。每个项都需要有标题段落、一个空行以及正文内容。无效或混合的输入会保持为普通可读的 Markdown 列表。

Markdown 步骤

Thu, 27 Aug 2026 00:00:00 GMT

当操作的顺序很重要时，使用 Steps 组件。该组件保持文章的阅读流不被打断：一条安静的编号轨道提供定位，而标题、段落、链接、列表和代码仍保留其原生的 Markdown 角色。

有序列表语法

将一个 Markdown 有序列表包裹在 :::steps 容器中。每个顶层列表项成为一步。

:::steps[Production deployment]
1. **Clone and prepare the workspace**

   Clone the repository and enter the project directory.

   ```powershell
   git clone https://github.com/LyraVoid/XiaoMai.git
   Set-Location XiaoMai
   ```

2. **Install dependencies**

   Use the repository's pinned package manager.

   ```powershell
   pnpm.cmd install
   ```

3. **Run project checks**

   Confirm Astro diagnostics and TypeScript checks pass.

   ```powershell
   npx.cmd astro check
   pnpm.cmd type-check
   ```

4. **Build the production site**

   Generate the static site and search index.

   ```powershell
   pnpm.cmd build
   ```
:::

:::steps[生产部署]

克隆并准备工作区

克隆仓库并进入项目目录。

git clone https://github.com/LyraVoid/XiaoMai.git
Set-Location XiaoMai

安装依赖

使用仓库锁定的包管理器。
```
pnpm.cmd install
```
运行项目检查

确认 Astro 诊断与 TypeScript 检查通过。
```
npx.cmd astro check
pnpm.cmd type-check
```
构建生产站点

生成静态站点与搜索索引。
```
pnpm.cmd build
```

:::

选项

:::steps[标题] 或 title="标题" 会添加可见标签与无障碍名称。
start=4 改变首个显示的步号。
容器必须恰好包含一个有序列表。无效或混合的输入会保持为普通可读的 Markdown，而不会被启发式地解释。
渲染在站点构建阶段完成，不引入任何客户端 JavaScript 或网络请求。

content-annotations

Thu, 27 Aug 2026 00:00:00 GMT

content-annotations把支撑性的上下文放在句子附近，又不把它直接放进阅读流中。点击小注释标记即可展开其内容。

基本语法

在普通正文中添加 [+label] 引用，然后在同一文章的其他位置定义对应的注释。

Astro renders most of a page ahead of time and hydrates **interactive islands** [+islands] only when they need to become interactive.

[+islands]:
  An island is an interactive UI component surrounded by static HTML. This keeps the default page lightweight while preserving focused interactivity.

Astro 会预先渲染页面的大部分内容，并仅在交互式孤岛 [+islands] 需要变为交互时才为其注水。

[+islands]: 孤岛是被静态 HTML 包围的交互式 UI 组件。这让默认页面保持轻量，同时保留聚焦的交互能力。

富文本内容

定义中可以包含段落、强调、链接、列表和行内代码 +rich-note，而周围的句子照常继续。

让首句自成一体。
当读者可能需要原始来源时，使用链接。
优先使用简洁的示例，例如 client:visible。

完整模型请参阅 Astro 孤岛文档。

多个定义

重复使用同一个标签 +review，在一个标记后呈现一组相关的简短注释。

诸如 [+missing] 之类的未定义引用会保持为普通文本，因此未完成的注释永远不会产生一个空控件。

Markdown admonitions

Thu, 27 Aug 2026 00:00:00 GMT

admonitions在保持文章阅读流的同时，让支撑信息在视觉上有所区分。每种形式都在服务端渲染，并使用同一个紧凑的 M3E 组件。

语义变体

::: note 部署上下文带空格的形式接受纯自定义标题，同时仍与引用语法兼容。 :::

:::info 将信息块用于帮助读者理解周围章节的中性上下文。 :::

:::tip[已有的 label 语法] 原始的方括号标签仍然可用，且可包含行内 Markdown 强调。 :::

[!IMPORTANT] GitHub Alert 语法会进入同一个渲染器，因此已有文章保持统一的可视语言。

:::warning 运行生产构建前，请检查环境变量。 :::

:::caution 不要随示例一起发布凭据、本地配置或私钥。 :::

可选细节

::: details 检查完整命令该折叠使用原生浏览器语义，无需客户端 JavaScript 即可保持键盘可达性。

npx.cmd astro check
pnpm.cmd build

它初始为关闭状态。
长代码可在自身代码块内滚动。
在窄屏上，容器保持在文章宽度内。 :::

编写语法

:::note[Existing title syntax]
Content
:::

::: warning Plume-compatible title syntax
Content
:::

> [!TIP]
> GitHub Alert syntax

::: details Optional content
Hidden until the reader opens it.
:::

MDX 集成与 M3E 原子组件

Thu, 20 Aug 2026 00:00:00 GMT

:::tip MDX（Markdown + JSX） 弥合了静态写作与应用程序界面之间的鸿沟。在 XiaoMai 中，作者可以在文章正文中无缝混合动态逻辑、响应式的 Svelte 5 组件以及 Material 3 设计令牌。 :::

1. Markdown 与 MDX 能力矩阵

特性	标准 Markdown（`.md`）	XiaoMai MDX（`.mdx`）	执行模式
排版与结构	完整支持	完整支持	静态 SSR
代码高亮	行号、边框、可折叠	行号、边框、可折叠	静态 SSR（Expressive Code）
图表与数学	Mermaid、KaTeX	Mermaid、KaTeX	客户端增强
admonitions Admonitions	Note、Tip、Important、Warning、Caution	Note、Tip、Important、Warning、Caution	静态 SSR
M3E 展示原子	不可用	直接集成（``、`<Skeleton>`）	纯 SSR（零客户端 JS）
Svelte 5 响应式孤岛	不可用	按需注水（`<Button>`、`<Switch>`）	`client:visible` 惰性注水
反馈与加载原子	不可用	动画形变（`<LoadingIndicator>`）	`client:visible` 响应式
动态 JSX 表达式	不可用	原生求值（`{authorInfo.ui}`）	编译期 / 客户端

2. 动态表达式与数据映射

MDX 允许在文件顶部使用 export const 声明作用域常量，它们可以行内求值或跨模板映射：

核心框架：{authorInfo.framework}
UI 引擎：{authorInfo.ui}
设计令牌：{authorInfo.tokens}
架构模式：{authorInfo.architecture}

数组与集合可以动态渲染为网格布局：

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6"> {showcaseItems.map((item, idx) => ( <div key={item.name} class="p-4 rounded-xl border border-[var(--outline-variant)] bg-[var(--surface-container-low)]"> <div class="flex items-center gap-2 mb-1"> <span class="w-6 h-6 rounded-full bg-[var(--primary)] text-[var(--on-primary)] text-xs flex items-center justify-center font-bold"> {idx + 1} </span> <span class="font-bold text-[var(--on-surface)]">{item.name}</span> </div> <p class="text-sm text-[var(--on-surface-variant)] m-0">{item.desc}</p> </div> ))} </div>

3. M3E 展示与布局原语（仅 SSR）

按照 XiaoMai 的组件架构（docs/atomic-structure.md），无状态展示组件会输出干净、无障碍的语义化 HTML，且不带来任何客户端运行时开销。

3.1 卡片容器（`Card.svelte`）

<div class="grid grid-cols-1 md:grid-cols-3 gap-4 my-6"> <Card variant="filled" class="!p-5"> <div class="font-bold text-[var(--primary)] mb-2">填充卡片</div> <div class="text-sm text-[var(--on-surface-variant)]">默认容器背景，无悬浮阴影。适合分组内容块。</div>

<div class="font-bold text-[var(--primary)] mb-2">悬浮卡片</div>
<div class="text-sm text-[var(--on-surface-variant)]">一级容器高度，附带交互状态分层以提升视觉焦点。</div>



<div class="font-bold text-[var(--primary)] mb-2">描边卡片</div>
<div class="text-sm text-[var(--on-surface-variant)]">清晰的 1px 描边边界，在中性表面上提供干净的分割。</div>

</div>

3.2 强调条与徽标（`AccentBar` 与 `Badge`）

<div class="flex-1"> <span class="font-bold text-lg">系统公告</span> <p class="text-xs text-[var(--on-surface-variant)] m-0">将 AccentBar 与 Badge 组合，构建醒目的视觉提示</p> </div> M3E v0.192 </div>

3.3 骨架占位（`Skeleton.svelte`）

用于预览布局骨架或搭建异步状态原型：

<div class="flex flex-col gap-1.5 flex-1">
  
  
</div>

</div>

4. 反馈与加载指示器

XiaoMai 提供高保真的 Material 3 Expressive 动效与反馈原子：

4.1 形变动加载指示器（`LoadingIndicator.svelte`）

基于 androidx.graphics.shapes 多边形形变实现，提供平滑的弹簧插值七形状动画：

</div>
<span class="text-xs text-[var(--on-surface-variant)]">不确定形状形变</span>

</div>

</div>
<span class="text-xs text-[var(--on-surface-variant)]">内含圆形变体</span>

</div>

</div>
<span class="text-xs text-[var(--on-surface-variant)]">确定进度（68%）</span>

</div> </div>

4.2 线性与不确定进度（`ProgressIndicator.svelte`）

</div>

<div class="flex flex-col gap-2 mt-2"> <div class="text-xs text-[var(--on-surface-variant)]">连续双线动画</div>

</div> </div>

5. 交互式 Svelte 5 孤岛

使用 client:visible 声明的组件在进入视口时，会通过 IntersectionObserver 惰性注水：

5.1 按钮矩阵（`Button.svelte`）

<div class="flex flex-wrap items-center gap-3 my-6 p-4 rounded-xl border border-[var(--outline-variant)]"> 填充按钮悬浮色调按钮描边文本按钮 </div>

5.2 筛选芯片与分段按钮（`Chips` 与 `SegmentedButton`）

</div>

</div> </div>

5.3 开关、复选框与滑块（`Switch`、`Checkbox`、`Slider`）

<div class="flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]"> <div class="flex items-center justify-between"> <span class="font-bold text-sm">带状态图标的开关</span>

</div>

<div class="flex items-center justify-between"> <span class="font-bold text-sm">选择复选框</span> <div class="flex items-center gap-4">

</div>

</div>

<div class="flex flex-col gap-2"> <span class="font-bold text-sm">色相频谱滑块</span>

</div> </div>

5.4 输入控件（`TextField.svelte`）

</div>

6. Markdown 扩展兼容性

XiaoMai 的 SSOT 统一插件管线保持了与所有 Markdown 扩展的完全兼容：

6.1 GitHub 仓库卡片

::github{repo="saicaca/fuwari"}

6.2 Mermaid 架构图

flowchart TD
    MDX[MDX 源入口] --> Compiler["@astrojs/mdx 编译器"]
    Compiler --> Plugins["Remark / Rehype SSOT 管线"]
    Plugins --> Islands["Svelte 5 交互式孤岛"]
    Islands --> Swup["Swup 客户端导航外壳"]
    Swup --> Screen["M3E 表现式文章视图"]

6.3 数学表达式（LaTeX / KaTeX）

行内公式：质能等价 $E = mc^2$ 与高斯积分 $\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$。

块级公式：

$$ \mathcal{L}{M3E} = \sum{i=1}^{N} \left( \text{Token}_i \cdot \text{ContrastRatio} \right) + \lambda |\text{MotionElegance}| $$

7. 总结

MDX 的原生集成让技术作者能够构建丰富、交互式的文档，同时保留 XiaoMai 极快的静态性能。所有组件都遵循 Material 3 Expressive 令牌设计体系，确保一致性、无障碍与视觉和谐。

Markdown 扩展功能

Sat, 01 Aug 2026 00:00:00 GMT

GitHub 仓库卡片

你可以添加动态卡片来链接到 GitHub 仓库，页面加载时，仓库信息会从 GitHub API 拉取。

::github{repo="Fabrizz/MMM-OnSpotify"}

使用代码 ::github{repo="<owner>/<repo>"} 创建 GitHub 仓库卡片。

::github{repo="saicaca/fuwari"}

Mermaid 图表

围栏的 mermaid 代码块会渲染为图表，并跟随当前的配色方案。

flowchart LR
    accTitle: Markdown 渲染管线
    accDescr: Markdown 源码被转换为语义化 HTML，随后增强为主题化 SVG 图表。
    A[Markdown 源码] --> B[Astro 内容管线]
    B --> C[语义化 HTML]
    C --> D[主题化图表]

admonitions（Admonitions）

支持以下几种admonitions：note tip important warning caution

:::note 提示用户应当留意的信息，即使只是略读也应注意到。 :::

:::tip 帮助用户更顺利完成的选填信息。 :::

:::important 用户成功所必需的关键信息。 :::

:::warning 由于潜在风险，需要用户立即关注的关键内容。 :::

:::caution 某项操作可能带来的负面后果。 :::

基本语法

:::note
提示用户应当留意的信息，即使只是略读也应注意到。
:::

:::tip
帮助用户更顺利完成的选填信息。
:::

自定义标题

admonitions的标题可以自定义。

:::note[MY CUSTOM TITLE] 这是一个带有自定义标题的 note。 :::

:::note[MY CUSTOM TITLE]
这是一个带有自定义标题的 note。
:::

GitHub 语法

[!TIP] GitHub 语法同样受支持。

> [!NOTE]
> GitHub 语法同样受支持。

> [!TIP]
> GitHub 语法同样受支持。

剧透

你可以给文字添加剧透。文字同样支持 Markdown 语法。

The content :spoiler[is hidden ayyy]!

The content :spoiler[is hidden **ayyy**]!

图片宽度与图注

独立的图片在其 alt 文本中可接受一个可选的 w-N% 宽度标记，以及一个渲染为图片下方居中图注的 Markdown 标题：

![图片描述 w-50%](./image.webp "可见图注")

有效宽度范围从 w-1% 到 w-100%；无效的标记会保留在 alt 文本中。宽度与图注相互独立——仅使用标题也会生成图注：

XiaoMai

XiaoMai 写作与使用指南

1. 创建新文章

2. Frontmatter 规范

示例

支持的 Frontmatter 字段

3. 文章加密

4. 组织文章文件

文件夹结构（本地资源推荐）

单文件结构（轻量随笔）

5. 丰富的 Markdown 与 MDX 扩展

5.1 admonitions（Admonitions）

5.2 GitHub 仓库卡片

5.3 Expressive Code 代码块

5.4 数学排版（KaTeX）

5.5 Mermaid 图表

5.6 图片画廊与 Fancybox 灯箱

6. 后续步骤与自定义

🔒 密码保护与文章加密演示

XiaoMai Markdown 增强功能

文件树

1. 嵌套列表语法（:::file-tree）

写作规则与标记

2. 终端输出语法（```file-tree）

配置选项

代码树

1. 容器语法（:::code-tree）

配置与标记

2. 本地目录自动导入（@[code-tree]）

图片画廊网格：语法与完整示例

最简语法

参数一览

图注与 Alt 文本

布局与裁剪

默认配置

三列纵向图片：3:4

三列横向图片：16:9

两列方形图片：1:1

四列与 contain

单列细节图片

稀疏五列行

六列中的混合图片

四列方形图片：1:1

六列横向图片：16:9

三列纵向图片：3:4

边缘敏感内容：cover 与灯箱

极端比例与 contain

透明图片

灯箱导航

检查清单

Expressive Code 示例

Expressive Code

语法高亮

常规语法高亮

渲染 ANSI 转义序列

编辑器与终端边框

代码编辑器边框

终端边框

覆盖边框类型

文本与行标记

标记整行与行范围

选择行标记类型（mark、ins、del）

为行标记添加标签

在独立行上添加长标签

使用类 diff 语法

将语法高亮与类 diff 语法结合

标记行内的个别文本

正则表达式

转义正斜杠

选择行内标记类型（mark、ins、del）

自动换行

为单个代码块配置自动换行

配置折行缩进

可折叠区块

行号

为单个代码块显示行号

更改起始行号

Mermaid 图表画廊

流程图

时序图

1. 嵌套列表语法（`:::file-tree`）

1. 容器语法（`:::code-tree`）

2. 本地目录自动导入（`@[code-tree]`）

四列与 `contain`

边缘敏感内容：`cover` 与灯箱

极端比例与 `contain`

3.1 卡片容器（`Card.svelte`）

3.2 强调条与徽标（`AccentBar` 与 `Badge`）

3.3 骨架占位（`Skeleton.svelte`）

4.1 形变动加载指示器（`LoadingIndicator.svelte`）

4.2 线性与不确定进度（`ProgressIndicator.svelte`）

5.1 按钮矩阵（`Button.svelte`）

5.2 筛选芯片与分段按钮（`Chips` 与 `SegmentedButton`）

5.3 开关、复选框与滑块（`Switch`、`Checkbox`、`Slider`）

5.4 输入控件（`TextField.svelte`）