xiaobuhui的博客

使用指南

Wed, 26 Aug 2026 00:00:00 GMT

欢迎使用 Shirone（白音）——一个围绕 Astro 7、Svelte 5 与 Material 3 Expressive（M3E） 设计系统打造的、富有表现力、动漫风格的个人博客主题。

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

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

1. 创建新文章

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

# Create a single-file post
pnpm new-post my-first-post

# Or create a post in a sub-directory
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 Shirone."
image: "./cover.webp"
tags: [M3E, Design, Frontend]
category: Guides
draft: false
comment: true
---

支持的 Frontmatter 字段

Field	Type	Required	Description
`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`	否	标记为草稿。草稿文章在生产环境构建（`pnpm build`）时会被隐藏。
`comment`	`boolean`	否	开关当前文章的评论区（默认：`true`）。
`lang`	`string`	否	与站点默认语言不同时的语言代码（如 `en`、`zh_CN`、`ja`）。

3. 文章加密

Shirone 提供客户端文章加密。对于私人日志或受限文章，可在 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. 组织文章文件

Shirone 同时支持基于文件夹的同布局与单文件两种布局：

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

将文章与其媒体资源放在一起，便于管理资源：

src/content/posts/
├── my-great-post/
│   ├── index.md           <-- Post content
│   ├── cover.webp         <-- Cover image (image: "./cover.webp")
│   └── diagram.png        <-- Inline illustration referenced in markdown

单文件结构（轻量散文）

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

5. 丰富的 Markdown 与 MDX 扩展

Shirone 开箱即用地内置了现代 Markdown 扩展：

5.1 提示框

使用容器指令来添加注释、提示、警告与提醒：

:::tip
Use admonition containers to highlight key takeaways or best practices.
:::

:::warning
Use warning containers to signal potential pitfalls or breaking changes.
:::

5.2 GitHub 仓库卡片

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

::github{repo="LyraVoid/Shirone"}

::github{repo="LyraVoid/Shirone"}

5.3 富表现力代码块

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

// 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 Visitor
    participant Page as Shirone Page
    participant Swup as Swup Container
    participant Audio as Persistent Shell

    Visitor->>Page: Click Navigation Link
    Page->>Swup: Trigger Seamless Transition
    Swup->>Page: Replace #swup-container
    Note over Audio: Background music plays continuously
    Page-->>Visitor: New Page Rendered

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

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

扩展语法总览

Wed, 19 Aug 2026 00:00:00 GMT

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

文件树

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

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

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

:::file-tree{title="Shirone source tree"}
- src
  - components/
    - ++ Navigation.svelte # added component
    - -- Button.astro # removed component
  - content
    - posts/
      - markdown-enhancements.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="Shirone source tree"}

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

编写规则与标记

差异状态：在条目前加上 ++（绿色背景与徽标）或 --（红色背景与删除线）来高亮变更。
注释：跟在 # 之后的任意文本会渲染为静音、右对齐的行内注释。
强调：用 **bold** 包裹文件名，可使关键文件获得醒目的视觉权重。
可折叠文件夹：由嵌套列表项推断出的目录默认展开。添加尾部斜杠（如 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="Shirone 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="Shirone Component Demo" 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="Anime Utilities" entry="status.ts"](/src/utils/anime)

@code-tree title="Site Configuration" entry="siteConfig.ts"

第一篇碎碎念

Sat, 12 Sep 2026 00:00:00 GMT

折腾一个自己的小站，往往是从一个很简单的念头开始的：想找个地方，把脑子里那些零零碎碎的东西存下来。

它们大多成不了正式的文章——不够系统，也不够完整。可能只是今天看到的一句话、一段没头没尾的联想，或者调试到深夜时突然想通的一个小问题。

于是就单独开了这么一块地方。

不追求篇篇有用，也不打算写给谁看。写得动就多写两句，写不动就放张图。先把想说的说出口，剩下的以后再说。

如果你也在折腾自己的小站，欢迎到关于我找我聊聊踩过的坑。

音频阅读器

Sat, 29 Aug 2026 00:00:00 GMT

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

音频阅读器会一直保持安静，直到你选择聆听。每个说话人按钮都只在被点击后才加载并播放其片段。

: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，不会加载音频阅读器资源。

Markdown 折叠面板

Fri, 28 Aug 2026 00:00:00 GMT

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

独立面板

默认情况下，各项目独立展开。给标题加 :+ 可让该项初始就展开，加 :- 可让其在组使用 expand 时保持收起。

::: collapse

环境要求

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

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

构建生产产物前，请检查内容流水线。
- pnpm.cmd check:manifest
- npx.cmd astro check :::

手风琴模式

当只需要保留一个展开项时，添加 accordion。浏览器直接对原生折叠元素分组，因此打开另一项会关闭上一项，且无需 hydration。

::: collapse accordion expand

expand 在这里的作用是什么？

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

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

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

编写语法

::: collapse accordion
- :+ First title

  First panel content.

- Second title with `code`

  Second panel content.
:::

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

Markdown 缩写

Fri, 28 Aug 2026 00:00:00 GMT

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

上下文示例

以 SSR 优先的输出，能在 JavaScript 运行前就保持初始文档可见。在衡量其阅读体验时，LCP 和 CLS 会揭示首屏可见内容是否既快又稳。

缩写也可以出现在普通 Markdown 旁边，例如 SSR 指南，但像 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]: 服务端渲染 *[LCP]: 最大内容绘制 *[CLS]: 累积布局偏移

编写边界

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

Markdown 片段复用

Fri, 28 Aug 2026 00:00:00 GMT

Shirone 可以将一个本地 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} -->

围栏代码内的 include 注释会保持字面原样。

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

选项组把并列的说明放在一起，无需重复周围的解释。每个选项都接受完整的块级 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 剧透

Fri, 28 Aug 2026 00:00:00 GMT

剧透把简短答案或剧情细节藏起来，却不从文档中移除。悬停、聚焦或激活原生控件即可展开内容。

行内细节

答案是 :spoiler[42]，而这句话在它周围仍是普通 Markdown。

剧透可以包含 inline code，也可以包含 :spoiler[带强调的更长细节]。

编写语法

The answer is :spoiler[42].

生成的 HTML 使用带 aria-expanded 状态的原生按钮。即使没有 JavaScript，悬停与聚焦仍能展开文本；可选的运行时则增加了点击与键盘切换。

Markdown 提示框

Thu, 27 Aug 2026 00:00:00 GMT

提示框让补充信息在视觉上保持独立，同时不打断文章阅读节奏。每种形式都在服务端渲染，并使用同一个紧凑的 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.
:::

内容注释

Thu, 27 Aug 2026 00:00:00 GMT

内容注释让补充背景紧贴句子，又不直接打断阅读流。点击小注标记即可展开内容。

基础语法

在普通正文中加入 [+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] 需要变得可交互时才进行 hydration。

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

富文本内容

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

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

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

多重定义

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

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

Markdown 步骤

Thu, 27 Aug 2026 00:00:00 GMT

对于讲究先后顺序的操作，请用步骤组件。该组件保持文章阅读流完整：一条安静的编号轨道提供定位，而标题、段落、链接、列表和代码仍保留各自原生的 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/Shirone.git
   Set-Location Shirone
   ```

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[Production deployment]

克隆并准备工作区

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

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

安装依赖

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

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

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

:::

选项

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

MDX 与交互组件

Thu, 20 Aug 2026 00:00:00 GMT

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

1. Markdown 与 MDX 能力矩阵

Feature	Standard Markdown (`.md`)	Shirone MDX (`.mdx`)	Execution Mode
排版与结构	完全支持	完全支持	静态 SSR
代码高亮	行号、边框、可折叠	行号、边框、可折叠	静态 SSR（富表现力代码块）
图表与数学	Mermaid、KaTeX	Mermaid、KaTeX	客户端增强
提示框	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）

根据 Shirone 的组件架构（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. 反馈与加载指示器

Shirone 具备高保真的 Material 3 Expressive 动效与反馈原子：

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

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

</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 扩展兼容性

Shirone 的 SSOT 统一插件管道保留了与所有 Markdown 扩展的完全兼容：

6.1 GitHub 仓库卡片

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

6.2 Mermaid 架构图

flowchart TD
    MDX[MDX Source Entry] --> Compiler["@astrojs/mdx Compiler"]
    Compiler --> Plugins["Remark / Rehype SSOT Pipeline"]
    Plugins --> Islands["Svelte 5 Interactive Islands"]
    Islands --> Swup["Swup Client Navigation Shell"]
    Swup --> Screen["M3E Expressive Article View"]

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 的原生集成让技术作者能够构建丰富、交互式的文档，同时保持 Shirone 极致快速的静态性能。所有组件都遵循 Material 3 Expressive 令牌设计系统，确保一致性、可访问性与视觉和谐。

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

Mon, 13 Jul 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 文本既是无障碍替代文字，也是默认图注。当图片带有可选标题时，则改用标题作为图注：

![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”中的竖图完整可见，留有空白且不被裁切。
五列与六列网格在宽屏上保留指定列数，随后按响应式规则收为两列或一列。

Mermaid 图表集

Thu, 02 May 2024 00:00:00 GMT

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

流程图

流程图用于描述一个流程，包括其中的判断以及返回到更早步骤的路径。

flowchart TD
    accTitle: Article publishing workflow
    accDescr: An article moves through writing, validation, preview, and build before publication. Failed validation returns it for revision.
    Draft[Write Markdown] --> Check{Validation passed?}
    Check -->|No| Revise[Revise article]
    Revise --> Check
    Check -->|Yes| Preview[Preview locally]
    Preview --> Build[Build static page]
    Build --> Publish[Publish]

时序图

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

sequenceDiagram
    accTitle: Diagram rendering after in-site navigation
    accDescr: A reader starts navigation, Swup replaces the article content, and the Mermaid renderer enhances diagrams on the new page.
    actor Reader
    participant Browser
    participant Swup
    participant Content as Article region
    participant Renderer as Mermaid renderer
    Reader->>Browser: Open another article
    Browser->>Swup: Start in-site navigation
    Swup->>Content: Replace page content
    Swup-->>Renderer: Emit content:replace
    Renderer->>Content: Find Mermaid containers
    Renderer-->>Browser: Insert themed SVGs

实体关系图

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

erDiagram
    accTitle: Blog content relationships
    accDescr: Authors write posts, posts receive comments, and join records connect posts to multiple tags.
    AUTHOR ||--o{ POST : writes
    POST ||--o{ COMMENT : receives
    POST ||--o{ POST_TAG : classified_by
    TAG ||--o{ POST_TAG : groups
    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 rendering modules
    accDescr: The content pipeline uses a Mermaid plugin to create fallback markup, which the client renderer later enhances into an SVG.
    class ContentPipeline {
        +render(markdown)
        +collectMetadata()
    }
    class MermaidPlugin {
        +transform(codeFence)
        +createFallback()
    }
    class DiagramRenderer {
        +initialize()
        +renderAll()
        +refreshTheme()
    }
    class ThemeTokens {
        +primary
        +surface
        +outline
    }
    ContentPipeline --> MermaidPlugin : uses
    DiagramRenderer --> MermaidPlugin : enhances output
    DiagramRenderer --> ThemeTokens : reads

状态图

状态图展示对象的生命周期，以及在各状态间触发切换的事件。

stateDiagram-v2
    accTitle: Article lifecycle
    accDescr: An article moves from draft to review and publication. It may return for revision or eventually be archived.
    [*] --> Draft
    Draft --> InReview : submit
    InReview --> Draft : request changes
    InReview --> Published : approve
    Published --> Draft : retract
    Published --> Archived : archive
    Archived --> [*]

XY 图

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

xychart-beta
    accTitle: Six weeks of content performance
    accDescr: Bars show normalized weekly publishing volume, while the line shows normalized reading completion.
    title "Six weeks of content performance"
    x-axis "Week" [1, 2, 3, 4, 5, 6]
    y-axis "Relative score" 0 --> 100
    bar [36, 52, 44, 68, 76, 84]
    line [48, 55, 62, 61, 73, 81]

饼图

饼图以紧凑的方式对比各类别在整体中所占的比例。

pie showData
    accTitle: Article topics by share
    accDescr: Engineering accounts for forty percent, design systems for twenty-five percent, and the remainder is split between guides and essays.
    title Article topics by share
    "Engineering" : 40
    "Design systems" : 25
    "Guides" : 20
    "Essays" : 15

甘特图

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

gantt
    accTitle: Theme release plan
    accDescr: The release plan moves from requirements and interaction design through component development, testing, and release.
    title Theme release plan
    dateFormat YYYY-MM-DD
    axisFormat %m/%d
    section Design
    Confirm requirements :done, brief, 2024-05-06, 2d
    Refine interactions :done, interaction, after brief, 3d
    section Implementation
    Develop components :active, components, after interaction, 6d
    Write examples :examples, after interaction, 4d
    section Validation
    Automated tests :tests, after components, 3d
    Release :milestone, release, after tests, 0d

思维导图

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

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

时间线

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

timeline
    title Mermaid support evolution
    Pipeline design : Detect Mermaid fences
                    : Preserve source fallback
    Client enhancement : Load the runtime on demand
                       : Apply theme tokens
    Reliability : Support Swup navigation
                : Verify responsive and accessible output

用户旅程图

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

journey
    accTitle: A reader understanding a technical article
    accDescr: The reader discovers an article, combines prose with diagrams to understand it, and then explores related topics.
    title A reader understanding a technical article
    section Discover
      Browse the article list: 4: Reader
      Choose a topic: 5: Reader
    section Understand
      Read the article: 4: Reader
      Inspect a relationship diagram: 5: Reader
    section Continue
      Open a related article: 4: Reader
      Bookmark the page: 3: Reader

Git 图

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

gitGraph
    accTitle: Mermaid feature branch history
    accDescr: A feature branch adds the renderer and tests before merging into the main branch for release.
    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[Backlog]
    docs[Write author documentation]
    examples[Expand example data]
  active[In progress]
    themes[Verify theme adaptation]
  complete[Complete]
    fallback[Source fallback]
    rendering[Client rendering]

桑基图

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

sankey-beta
Landing,Reading,720
Discovery,Reading,430
Reading,Explore,360
Reading,Topics,210
Reading,Outbound,140

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

Markdown 扩展特性

Wed, 01 May 2024 00:00:00 GMT

GitHub 仓库卡片

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

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

用下面的代码创建一个 GitHub 仓库卡片：::github{repo="<owner>/<repo>"}。

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

Mermaid 图表

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

flowchart LR
    accTitle: Markdown rendering pipeline
    accDescr: Markdown source is transformed into semantic HTML and then enhanced as a themed SVG diagram.
    A[Markdown source] --> B[Astro content pipeline]
    B --> C[Semantic HTML]
    C --> D[Themed diagram]

提示框

支持以下类型的提示框：note tip important warning caution

:::note 强调用户在快速浏览时也应留意的信息。 :::

:::tip 帮助用户更顺利完成的补充信息。 :::

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

:::warning 因潜在风险而需要用户立即关注的重要内容。 :::

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

基础语法

:::note
Highlights information that users should take into account, even when skimming.
:::

:::tip
Optional information to help a user be more successful.
:::

自定义标题

提示框的标题可以自定义。

:::note[我的自定义标题] 这是一条带有自定义标题的提示。 :::

:::note[MY CUSTOM TITLE]
This is a note with a custom title.
:::

GitHub 语法

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

> [!NOTE]
> The GitHub syntax is also supported.

> [!TIP]
> The GitHub syntax is also supported.

剧透

你可以在文字中加入剧透。文字同样支持 Markdown 语法。

内容 :spoiler[被隐藏了 ayyy]！

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

图片宽度与图注

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

![Image description w-50%](./image.webp "Visible caption")

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

代码块示例

Wed, 10 Apr 2024 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')

Markdown 基础示例

Sun, 01 Oct 2023 00:00:00 GMT

一级标题

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

第二段。斜体、粗体和 monospace。项目符号列表长这样：

这一个
那一个
另一个

注意，--- 不考虑星号的情况下 --- 实际正文从左侧第 4 列开始。

引用块像这样写。

如果你愿意，它们可以跨多个段落。

用 3 个连字符表示破折号。用 2 个连字符表示范围（例如，"全部在第 12--14 章"）。三个点 ... 会被转换为省略号。支持 Unicode。☺

二级标题

下面是一个有序列表：

第一项
第二项
第三项

再次注意，实际正文从第 4 列开始（距左侧 4 个字符）。下面是一个代码示例：

# Let me re-iterate ...
for i in 1 .. 10 { do-something(i) }

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

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

（这样复制粘贴更方便）。你还可以为围栏代码块加上标记，让 Pandoc 对其做语法高亮：

import time
# Quick, count to ten!
for i in range(10):
    # (but not *too* quick)
    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 玻璃透明

表格：鞋子、其尺码及制作材料

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

关键词说明

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

绿色树叶、青草、青蛙以及其他难以成为的事物。

下面是一条水平分隔线。

下面是一个定义列表：

苹果 : 适合做苹果酱。橙子 : 柑橘类！番茄 : 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 Aug 2023 00:00:00 GMT

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

---
title: Include Video in the Post
published: 2023-10-19
// ...
---

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

YouTube

::youtube{id="5gIf0_xpFPI" title="YouTube 视频" preload="auto"}

Bilibili

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

AcFun

::acfun{acid="ac48649632" title="AcFun 视频" preload="auto"}

ArtPlayer

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

xiaobuhui的博客

使用指南

1. 创建新文章

2. Frontmatter 规范

示例

支持的 Frontmatter 字段

3. 文章加密

4. 组织文章文件

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

单文件结构（轻量散文）

5. 丰富的 Markdown 与 MDX 扩展

5.1 提示框

5.2 GitHub 仓库卡片

5.3 富表现力代码块

5.4 数学排版（KaTeX）

5.5 Mermaid 图

5.6 图片画廊与 Fancybox 灯箱

6. 后续步骤与自定义

🔒 文章密码保护演示

扩展语法总览

文件树

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

编写规则与标记

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

配置选项

代码树

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

配置与标记

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

第一篇碎碎念

音频阅读器

片段清单

Markdown 折叠面板

独立面板

手风琴模式

编写语法

Markdown 缩写

上下文示例

定义术语

编写边界

Markdown 片段复用

Markdown 标记高亮

默认强调

语义颜色

编写语法

Markdown 选项组

选择包管理器

运行项目

多种可选方案

编写语法

Markdown 剧透

行内细节

编写语法

Markdown 提示框

语义变体

可选详情

编写语法

内容注释

基础语法

富文本内容

多重定义

Markdown 步骤

有序列表语法

选项

MDX 与交互组件

1. Markdown 与 MDX 能力矩阵

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

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

3.1 卡片容器（Card.svelte）

3.2 强调条与徽章（AccentBar 与 Badge）

3.3 骨架占位（Skeleton.svelte）

4. 反馈与加载指示器

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

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

5. 交互式 Svelte 5 孤岛

5.1 按钮矩阵（Button.svelte）

5.2 过滤芯片与分段按钮（Chips 与 SegmentedButton）

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

5.4 输入控件（TextField.svelte）

6. Markdown 扩展兼容性

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

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

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

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`）

四列与 `contain`

边缘关键内容：`cover` 与灯箱

极端比例与 `contain`