XiaoMai 写作与使用指南

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

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

1. 创建新文章#

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

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

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

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

2. Frontmatter 规范#

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

示例#

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

支持的 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 中指定密码：

1
---
2
title: "Private Research Notes"
3
published: 2026-08-26
4
encrypted: true
5
password: "your-secret-passphrase"
6
passwordHint: "Favorite anime character"
7
hideHomeContent: true
8
---

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

4. 组织文章文件#

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

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

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

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

单文件结构（轻量随笔）#

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

5. 丰富的 Markdown 与 MDX 扩展#

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

5.1 admonitions（Admonitions）#

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

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

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

DETAILS

使用详情容器来收纳可折叠的可选内容，默认收起。

5.2 GitHub 仓库卡片#

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

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

GrowWheatXiaoMai

5.3 Expressive Code 代码块#

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

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

4
const theme = themeFromSourceColor(argbFromHex("#f472b6"));
5
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 集成，支持无损缩放、平移手势与全屏预览：

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

6. 后续步骤与自定义#

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

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. 后续步骤与自定义#

继续阅读

换条路线

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. 后续步骤与自定义#

分享文章

沿着主题读

换条路线