Lambent's Blog

Shirone 编写与使用指南

2026-08-26T00:00:00.000Z

欢迎使用 Shirone（白音）——一款以 Astro 7、Svelte 5 和 Material 3 Expressive (M3E) 设计系统为基础打造、富有表现力且受动画风格启发的博客主题。

本指南将介绍文章创建、Frontmatter 规范、目录结构，以及完整的内置 Markdown 和 MDX 扩展。

:::tip Shirone 优先在服务器端渲染内容（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: "探索 Material 3 Expressive 设计"
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: "深入了解 Shirone 中的动态 HCT 色彩科学和流畅过渡效果。"
image: "./cover.webp"
tags: [M3E, 设计, 前端]
category: 指南
draft: false
comment: true
---

支持的 Frontmatter 字段

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

3. 文章加密

Shirone 提供客户端文章加密。这是一种静态密码门禁，并非服务器端访问控制：加密载荷和资源 URL 仍可公开下载，因此不要用它保护真正机密的文件或受监管的信息。若要限制日记或文章的访问，请在 Frontmatter 中设置密码：

---
title: "私人研究笔记"
published: 2026-08-26
encrypted: true
password: "your-secret-passphrase"
passwordHint: "最喜欢的动画角色"
hideHomeContent: true
---

encrypted：设为 true 以启用加密；
password：解锁文章所需的密码字符串或数字；
passwordHint：显示在密码输入框上方的可选提示；
hideHomeContent：在首页隐藏字数和内容预览，避免信息泄露。

4. 组织文章文件

Shirone 同时支持文章与资源共置于文件夹中，以及单文件布局：

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

将文章与媒体文件放在一起，可以简化资源管理：

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 扩展

Shirone 开箱即用地集成了多种现代 Markdown 扩展：

5.1 提示容器

使用容器指令添加说明、提示、警告和提醒：

:::tip
使用提示容器突出重点结论或最佳实践。
:::

:::warning
使用警告容器说明潜在问题或不兼容变更。
:::

5.2 GitHub 仓库卡片

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

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

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

5.3 Expressive Code 代码块

增强型代码块支持语法高亮、文件名徽标、行号和指定行高亮：

// 动态派生 HCT 颜色令牌
import { argbFromHex, themeFromSourceColor } from "@material/material-color-utilities";

const theme = themeFromSourceColor(argbFromHex("#f472b6"));
console.log("主色令牌：", 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 Shirone 页面
    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 分享想法并提出问题。

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

2026-08-20T00:00:00.000Z

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

Shirone Markdown 扩展功能

2026-08-19T00:00:00.000Z

Shirone 提供了一系列主题专属的 Markdown 扩展和自定义语法容器。这些扩展基于原生 unified AST 处理流程构建，会在站点构建期间渲染为语义清晰、易于访问的 HTML，不会产生客户端 JavaScript hydration 开销，并且完全遵循 M3E 设计令牌。

文件树

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

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

如果要直接使用 Markdown 嵌套列表书写文件层级，请使用 :::file-tree 块级指令。

:::file-tree{title="Shirone 源码目录"}
- src
  - components/
    - ++ Navigation.svelte # 新增组件
    - -- Button.astro # 已移除组件
  - content
    - posts/
      - markdown-enhancements.md
  - layouts/
    - PostLayout.astro
  - plugins
    - markdown/
      - rehype-file-tree.mjs
  - styles
    - markdown/
      - trees.css
  - **content.config.ts** # 重要文件
- public/
  - favicon.svg
- package.json
:::

:::file-tree{title="Shirone 源码目录"}

src
- components/
  - ++ Navigation.svelte # 新增组件
  - -- Button.astro # 已移除组件
- content
  - posts/
    - markdown-enhancements.md
- layouts/
  - PostLayout.astro
- plugins
  - markdown/
    - rehype-file-tree.mjs
- styles
  - markdown/
    - trees.css
- content.config.ts # 重要文件
public/
- favicon.svg
package.json :::

编写规则与标记

差异状态：在条目前加上 ++（绿色背景和徽标）或 --（红色背景和删除线），即可突出变更。
注释：# 后的文本会作为弱化、右对齐的行内注释显示。
强调：用 **粗体** 包裹名称，即可突出显示重要文件。
可折叠文件夹：根据嵌套列表推断出的目录默认展开。添加尾随斜杠（如 components/）即可创建默认折叠的目录，读者可以点击或使用键盘导航展开。

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

如果已使用 tree 等命令行工具生成目录树文本，可直接将其粘贴到 file-tree 围栏代码块中。Unicode 分支字符（├──、└──、│）和 ASCII 分支都会自动解析。

```file-tree title="构建输出" 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 组件示例" height="380px" entry="src/Button.svelte"}
```svelte title="src/Button.svelte"



```

```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"}

.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="status.ts"](/src/utils/anime)

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

Audio Reader：日系动画神秘语音集

2026-08-29T00:00:00.000Z

这些简短的日语语音片段，仿佛从动画场景的一角拾取而来：俏皮的呼唤、明快的问候、轻轻的笑声，以及几句出处不明的话语。它们是用于营造氛围的声音片段，并非台词转录，不妨让声音本身传达情绪。

在你选择收听之前，Audio Reader 不会加载这些片段。点击每个语音按钮后，才会加载并播放对应音频。

:audio-reader[音频标题]{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 折叠面板

2026-08-28T00:00:00.000Z

折叠面板可以将相关的可选详情收纳在一起。标题和正文均支持 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
- :+ 第一个标题

  第一个面板的内容。

- 带有 `code` 的第二个标题

  第二个面板的内容。
:::

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

Markdown 缩写词

2026-08-28T00:00:00.000Z

缩写词可以让技术文章更加简洁，同时也为有需要的读者保留完整释义。定义后的术语会渲染为原生 abbr 元素，读者将鼠标悬停其上或使用辅助技术时，都可以查看释义。

正文示例

SSR 优先的输出方式可以确保 JavaScript 运行前，初始文档就已可见。评估阅读体验时，LCP 和 CLS 可以反映首屏内容是否快速呈现且保持稳定。

缩写词也可以出现在普通 Markdown 内容中，例如 SSR 相关说明；但代码字面量（如 SSR）和链接（如 LCP 文档）不会受到影响。

定义术语

定义可以放在同一 Markdown 文档的任意位置。定义本身不会显示为段落，只有本文中匹配的术语才会应用语义化缩写效果。

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

SSR 会在客户端代码运行前提供 HTML 响应。

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

编写规则

术语必须以字母或数字开头，后续可以包含字母、数字、句点、下划线、加号和连字符。每条定义仅对当前文章生效；无效或重复的定义会保留为普通 Markdown，不会悄悄覆盖已有术语。

Markdown 文件包含

2026-08-28T00:00:00.000Z

Shirone 可以包含本地 Markdown 文件，或安全地截取其中一部分。

同时也支持包含整个文件和指定行范围：

围栏代码中的包含注释会保持原样。

Markdown 标记高亮

2026-08-28T00:00:00.000Z

标记高亮可以突出某个短语，而无需将整段内容变成独立组件。构建时，它们会被渲染为原生元素，并继承当前启用的 M3E 配色系统。

默认强调

如果希望使用文章的主色来突出内容，请使用 ==text==。例如，在普通段落中突出 ==读者应当记住的一项决定==。

如果需要更明显的层级，标记中也可以嵌套 ==Markdown 强调语法==。

语义颜色

如果需要表达不同的语义色调，可以添加后缀。可用变体包括 primary、secondary、tertiary、error 和 tip。

==Primary 将短语与当前主题色关联起来=={.primary}
==Secondary 以较柔和的方式表达补充区分=={.secondary}
==Tertiary 添加另一种编辑提示色=={.tertiary}
==Error 标记需要修正的情况=={.error}
==Tip 突出实用建议=={.tip}

编写语法

==Primary marker==

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

行内代码（如 ==标记语法示例==）和围栏代码示例会保持原样，因此文档可以讲解语法而不会实际触发高亮。

Markdown 选项组

2026-08-28T00:00:00.000Z

选项组可以将功能相同的说明放在一起，而不必重复周围的解释。每个选项都支持完整的块级 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

在此填写 npm 相关说明。

@tab:active **pnpm**#pnpm

在此填写 pnpm 相关说明。

:::

每个选项组至少需要两个 @tab 区块，并且每个区块的标记与正文之间都需要有一个空行。无效或不完整的选项组会保留为可读的普通 Markdown。

Markdown 剧透内容

2026-08-28T00:00:00.000Z

剧透语法可以隐藏简短答案或剧情细节，但不会将其从文档中移除。将鼠标悬停在原生控件上、聚焦控件或激活控件，即可显示内容。

行内详情

答案是 :spoiler[42]，周围的句子仍然是普通 Markdown。

剧透内容也可以包含 行内代码，例如 :spoiler[带有强调的较长细节]。

编写语法

答案是 :spoiler[42]。

生成的 HTML 使用带有 aria-expanded 状态的原生按钮。即使没有 JavaScript，鼠标悬停和键盘聚焦仍可显示文本；可选运行时则会添加点击和键盘切换功能。

Markdown 提示容器

2026-08-27T00:00:00.000Z

提示容器可以在不打断文章阅读节奏的前提下，突出显示补充信息。所有形式都会在服务器端渲染，并使用统一、紧凑的 M3E 组件。

语义变体

::: note 部署说明带空格的写法支持普通自定义标题，同时兼容原有语法。 :::

:::info 使用信息块补充中性背景，帮助读者理解当前章节。 :::

:::tip[现有的标签写法] 原有的方括号标签写法仍然可用，其中也可以包含 Markdown 行内强调。 :::

[!IMPORTANT] GitHub Alert 语法也会进入同一渲染流程，因此现有文章仍能保持统一的视觉风格。

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

:::caution 请勿在示例中发布凭据、本地配置或私钥。 :::

可选详情

::: details 查看完整命令此折叠区域使用浏览器原生语义，即使没有客户端 JavaScript，也可以通过键盘访问。

npx.cmd astro check
pnpm.cmd build

默认处于收起状态。
较长的代码可以在代码块内部滚动。
在窄屏上，容器宽度仍不会超出文章区域。 :::

编写语法

:::note[现有标题写法]
容器内容
:::

::: warning 兼容 Plume 的标题写法
容器内容
:::

> [!TIP]
> GitHub Alert 写法

::: details 可选内容
读者展开后显示。
:::

内容注释

2026-08-27T00:00:00.000Z

内容注释可以将补充背景放在相关句子附近，而不直接插入正文阅读流。激活小型注释标记即可查看说明。

基本语法

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

Astro 会预先渲染页面的大部分内容，只在 **交互岛屿** [+islands] 需要变为可交互状态时才对其进行 hydration。

[+islands]:
  交互岛屿是由静态 HTML 包围的交互式 UI 组件。这样既能让页面默认保持轻量，又能保留所需的局部交互。

Astro 会预先渲染页面的大部分内容，只在 交互岛屿 [+islands] 需要变为可交互状态时才对其进行 hydration。

[+islands]: 交互岛屿是由静态 HTML 包围的交互式 UI 组件。这样既能让页面默认保持轻量，又能保留所需的局部交互。

丰富内容

注释定义可以包含段落、强调、链接、列表和行内代码 +rich-note，周围句子的阅读仍会自然延续。

确保第一句话本身完整清晰。
如果读者可能需要查看主要来源，请提供链接。
优先使用 client:visible 这类简洁示例。

完整说明请参阅 Astro 交互岛屿文档。

多条注释

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

未定义的引用（例如 [+missing]）会保留为普通文本，因此尚未完成的定义不会生成空控件。

Markdown 步骤流

2026-08-27T00:00:00.000Z

对于有严格先后顺序的流程，可以使用步骤流。该组件不会打断文章的阅读节奏：简洁的编号轨道帮助读者定位，而标题、段落、链接、列表和代码仍保留各自原生的 Markdown 语义。

有序列表语法

使用 :::steps 容器包裹一个 Markdown 有序列表。每个顶层列表项都会成为一个步骤。

:::steps[部署到生产环境]
1. **克隆并准备工作区**

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

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

2. **安装依赖**

   使用仓库指定的包管理器。

   ```powershell
   pnpm.cmd install
   ```

3. **运行项目检查**

   确认 Astro 诊断和 TypeScript 检查均已通过。

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

4. **构建生产站点**

   生成静态站点和搜索索引。

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

:::steps[部署到生产环境]

克隆并准备工作区

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

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="标题" 可以添加可见标题和无障碍名称。
start=4 可以更改起始步骤编号。
容器中必须恰好包含一个有序列表。无效或混杂的输入会保留为普通且可读的 Markdown，不会被启发式地解析。
内容会在站点构建期间完成渲染，不会增加客户端 JavaScript 或网络请求。

MDX 集成与 M3E 原子组件

2026-08-20T00:00:00.000Z

:::tip **MDX（Markdown + JSX）**连接了静态写作与应用界面。在 Shirone 中，作者可以直接在文章内容中无缝组合动态逻辑、响应式 Svelte 5 组件和 Material 3 设计令牌。 :::

1. Markdown 与 MDX 功能对比

功能	标准 Markdown（`.md`）	Shirone MDX（`.mdx`）	执行模式
排版与结构	完整支持	完整支持	静态 SSR
代码高亮	行号、框架、可折叠	行号、框架、可折叠	静态 SSR（Expressive Code）
图表与数学公式	Mermaid、KaTeX	Mermaid、KaTeX	客户端增强
提示容器	说明、提示、重要、警告、注意	说明、提示、重要、警告、注意	静态 SSR
M3E 展示原子组件	不支持	直接集成（``、）	纯 SSR（无客户端 JS）
Svelte 5 响应式岛屿	不支持	按需 hydration（	使用 `client:visible` 延迟 hydration
反馈与加载原子组件	不支持	动态变形（）	`client:visible` 响应式
动态 JSX 表达式	不支持	原生求值（`{authorInfo.ui}`）	编译时／客户端

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

MDX 支持在文件顶部使用 export const 声明作用域内常量，并在正文中直接求值或映射到模板中：

Core Framework: {authorInfo.framework}
UI Engine: {authorInfo.ui}
Design Tokens: {authorInfo.tokens}
Architecture Pattern: {authorInfo.architecture}

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

{showcaseItems.map((item, idx) => (

{idx + 1} {item.name}

{item.desc}

))}

3. M3E Display and Layout Primitives (SSR-Only)

根据 Shirone 的组件架构（docs/atomic-structure.md），无状态展示组件会输出简洁、易访问的语义化 HTML，且不会附带客户端运行时负载。

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

填充卡片

使用默认容器背景，不带阴影。适合组合展示内容块。

浮起卡片
使用第 1 层容器高度，并通过交互状态叠层增强视觉焦点。



描边卡片
清晰的 1px 描边可在中性色表面上形成明确分隔。

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

系统公告

组合使用 AccentBar 和 Badge，构建醒目的视觉提示

M3E v0.192

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

用于预览布局骨架或模拟异步状态：

4. 反馈与加载指示器

Shirone 提供完整实现 Material 3 Expressive 动效规范的反馈原子组件：

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

该组件使用 androidx.graphics.shapes 实现多边形变形，提供流畅的弹簧插值七形态动画：


不确定进度形态变换


容器内圆形变体


确定进度（68%）

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

流程编译 80%

连续双线动画

5. 交互式 Svelte 5 岛屿

声明为 client:visible 的组件会在进入视口时通过 IntersectionObserver 延迟 hydration：

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

填充按钮浮起按钮柔和按钮描边按钮文本按钮

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

M3E 筛选芯片

分段控件

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

带状态图标的开关

复选框

色相光谱滑块

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

6. Markdown 扩展兼容性

Shirone 的 SSOT unified 插件处理流程与所有 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 设计令牌体系，确保一致性、无障碍性和视觉协调。

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

2026-07-13T00:00:00.000Z

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

同一画廊中的图片使用相同的卡片比例。默认情况下，图片会从中心裁剪并填满卡片，让每一行保持整齐；点击图片即可在灯箱中查看完整原图。每个画廊都有独立的灯箱分组，不会与文章中的其他图片混在一起。

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

最简语法

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

:::grid
![图片说明](./image-1.webp)

![图片说明](./image-2.webp)
:::

每张图片都必须单独占一个段落，图片之间以空行分隔。画廊中只能放图片；段落、列表和代码块应写在容器之外。

下面是最简语法的渲染结果。不设置参数时，网格默认使用三列、16/10 比例和 cover 模式。

:::grid

:::

参数一览

在起始指令后面的花括号中填写所有参数：:::grid{parameter="value"}。

参数	可用值	默认值	用途
`columns`	Integers from `1` to `6`	`3`	桌面端每行的列数。无效值会回退为 `3`。
`aspect`	A positive ratio, such as `16/9`, `3/4`, or `1/1`	`16/10`	卡片的显示比例，而非原图比例。
`fit`	`cover`, `contain`	`cover`	图片适配模式。`cover` 会裁剪并填满卡片；`contain` 会保留完整图片，但可能出现留白。

完整示例：

:::grid{columns="3" aspect="16/9" fit="cover"}
![第一张图片](./image-1.webp "可选说明")

![第二张图片](./image-2.webp "可选说明")

![第三张图片](./image-3.webp "可选说明")
:::

以下结果使用了上方的三列横图语法。请比较卡片比例、列数，以及标题优先于 alt 文本成为说明文字的效果：

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

:::

说明文字与 Alt 文本

图片的 alt 文本既是无障碍替代文本，也是默认说明文字。如果图片设置了可选标题，则会优先使用该标题作为说明文字：

![用于无障碍访问的文本](./image.webp "显示在图片下方的说明文字")

同一行中的说明文字会在每张卡片底部对齐。即使某条说明换行，也不会导致其他说明的高度错位。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-1.webp "可选说明")

![图片说明](./image-2.webp "可选说明")
:::

:::grid{columns="3" aspect="16/9" fit="contain"}
![图片说明](./image-1.webp "可选说明")

![图片说明](./image-2.webp "可选说明")
:::

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

:::

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

:::

默认配置

不设置属性时，默认使用三列、16/10 比例和 cover 裁剪。以下三张竖图用于验证默认裁剪和说明文字。

:::grid
![图片说明](./image-1.webp)

![图片说明](./image-2.webp)

![图片说明](./image-3.webp)
:::

:::grid

:::

三列竖图：3:4

设置 aspect="3/4" 后，三张竖图会填充比例统一的纵向卡片。如果原图比例不同，cover 会从中心向边缘裁剪。

:::grid{columns="3" aspect="3/4"}
![竖图说明](./portrait-1.webp)

![竖图说明](./portrait-2.webp)

![竖图说明](./portrait-3.webp)
:::

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

:::

三列横图：16:9

这组示例在三列布局中展示常见的视频封面比例。当横图比例接近卡片比例时，裁剪会很少。

:::grid{columns="3" aspect="16/9"}
![横图说明](./landscape-1.webp)

![横图说明](./landscape-2.webp)

![横图说明](./landscape-3.webp)
:::

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

:::

两列方图：1:1

需要较大的预览卡片时，两列布局十分合适。第三张图片会移至下一行，最后一行保持网格轨道宽度，不会拉伸图片以填满整行。

:::grid{columns="2" aspect="1/1"}
![方图说明](./square-1.webp)

![方图说明](./square-2.webp)

![方图说明](./square-3.webp)
:::

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

:::

使用 `contain` 的四列布局

fit="contain" 不会裁剪原图。当图片比例与卡片比例不同时，会露出主题背景。这是预期效果，并非布局问题。此示例还用于验证四列网格和独立灯箱分组互不干扰。

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

![图片说明](./image-2.webp)

![图片说明](./image-3.webp)
:::

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

:::

单列细节图片

图片需要更大的阅读尺寸时，适合使用单列布局。在桌面、平板和手机上都会保持单列，灯箱中仍可查看原图。

:::grid{columns="1" aspect="16/9"}
![图片说明](./detail.webp)
:::

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

稀疏五列布局

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

:::grid{columns="5" aspect="1/1"}
![缩略图说明](./thumb-1.webp)

![缩略图说明](./thumb-2.webp)

![缩略图说明](./thumb-3.webp)
:::

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

:::

六列混合图片

六列是当前支持的最大列数。混排横图和竖图，可以验证 cover 裁剪、窄卡片中的说明文字，以及桌面端的紧凑布局。为了保证文章易读，通常建议使用两到四列。

:::grid{columns="6" aspect="1/1"}
![图片说明](./image-1.webp)

![图片说明](./image-2.webp)

![图片说明](./image-3.webp)

![图片说明](./image-4.webp)

![图片说明](./image-5.webp)

![图片说明](./image-6.webp)
:::

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

:::

四列方图：1:1

四张比例相同的方图适合典型的四列布局。桌面端会将四张图片排列在一行；平板端折叠为两列，手机端则为一列。

:::grid{columns="4" aspect="1/1"}
![方图说明](./square-1.webp)

![方图说明](./square-2.webp)

![方图说明](./square-3.webp)

![方图说明](./square-4.webp)
:::

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

:::

六列横图：16:9

六列横图适合缩略图预览、作品集和屏幕截图索引。即使原图比例略有不同，cover 也能一致地填满每个 16/9 卡片。

:::grid{columns="6" aspect="16/9"}
![横图说明](./landscape-1.webp)

![横图说明](./landscape-2.webp)

![横图说明](./landscape-3.webp)

![横图说明](./landscape-4.webp)

![横图说明](./landscape-5.webp)

![横图说明](./landscape-6.webp)
:::

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

:::

三列竖图：3:4

这组六张竖图展示人物图片、海报或手机截图的常见布局。图片分为两行、每行三张，说明文字在卡片底部对齐。

:::grid{columns="3" aspect="3/4"}
![竖图说明](./portrait-1.webp)

![竖图说明](./portrait-2.webp)

![竖图说明](./portrait-3.webp)

![竖图说明](./portrait-4.webp)

![竖图说明](./portrait-5.webp)

![竖图说明](./portrait-6.webp)
:::

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

:::

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

这些图片的边缘处包含重要文字或细节。cover 可以让网格保持整齐，但可能裁掉边缘；点击图片即可在灯箱中查看未裁剪的原图。边缘细节重要时，请使用清晰的说明文字，或改用下方的 contain 模式。

:::grid{columns="3" aspect="16/9" fit="cover"}
![边缘关键内容](./critical-1.webp "打开灯箱查看完整的边缘内容")

![边缘关键内容](./critical-2.webp "打开灯箱查看完整的边缘内容")

![边缘关键内容](./critical-3.webp "打开灯箱查看完整的边缘内容")
:::

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

:::

使用 `contain` 处理极端比例

对于横幅、长屏幕截图和其他比例极端的图片，contain 可以完整显示原图。与 cover 不同，它可能会露出主题背景，但不会裁剪图片内容。

:::grid{columns="3" aspect="16/9" fit="contain"}
![完整屏幕截图说明](./wide-1.webp)

![完整屏幕截图说明](./wide-2.webp)

![完整屏幕截图说明](./wide-3.webp)
:::

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

:::

透明图片

透明图片可以透出卡片的主题背景。此单列 contain 示例便于查看透明区域、原图边缘和灯箱效果。

:::grid{columns="1" aspect="16/9" fit="contain"}
![透明图片说明](./transparent.webp)
:::

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

灯箱导航

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

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

检查清单

每个网格中的图片尺寸一致，说明文字显示在卡片下方。
鼠标悬停时图片会轻微放大；点击后可以缩放、旋转，也可以使用键盘切换。
点击“16:9 测试图片一”后，灯箱只能浏览该分组中的另外两张横图。
视口宽度低于 768px 时，网格最多显示两列；低于 480px 时改为单列。
“使用 contain 的四列布局”中的竖图应完整显示，留有空白且不会被裁剪。
五列和六列网格在宽屏上保持指定列数，再根据响应式规则折叠为两列或一列。

Mermaid 图表集

2024-05-02T00:00:00.000Z

Mermaid 可以将 Markdown 中的文本描述转换为图表。以下示例使用 Shirone 的内容工作流，展示技术文章和项目笔记中常见的图表类型。

流程图

流程图用于描述一个流程，包括决策分支以及返回前序步骤的路径。

flowchart TD
    accTitle: 文章发布流程
    accDescr: 文章在发布前依次经过撰写、验证、预览和构建。验证失败时会返回修改。
    Draft[撰写 Markdown] --> Check{验证通过？}
    Check -->|否| Revise[修改文章]
    Revise --> Check
    Check -->|是| Preview[本地预览]
    Preview --> Build[构建静态页面]
    Build --> Publish[发布]

时序图

时序图按照时间顺序展示参与者之间的交互。此示例展示一次 Swup 导航从发起请求到渲染 Mermaid 图表的过程。

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

实体关系图

实体关系图用于描述结构化数据及其关系，例如作者、文章、标签和评论之间的联系。

erDiagram
    accTitle: 博客内容关系
    accDescr: 作者撰写文章，文章接收评论，关联记录则将文章与多个标签连接起来。
    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 渲染模块
    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 --> 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 设计
    确认需求 :done, brief, 2024-05-06, 2d
    完善交互 :done, interaction, after brief, 3d
    section 实现
    开发组件 :active, components, after interaction, 6d
    编写示例 :examples, after interaction, 4d
    section 验证
    自动化测试 :tests, after components, 3d
    发布 :milestone, release, after tests, 0d

思维导图

思维导图以一个中心主题为起点，展开相关领域和支撑概念。

mindmap
  root((Shirone))
    内容体验
      Markdown
      搜索
      图表
    界面系统
      M3E 令牌
      响应式布局
      配色方案
    工程质量
      Astro Check
      Playwright
      无障碍

时间线

时间线可以概括重要事件或阶段，无需提供精确的日历时长。

timeline
    title Mermaid 支持的演进
    流程设计 : 检测 Mermaid 围栏代码
             : 保留源码回退内容
    客户端增强 : 按需加载运行时
              : 应用主题令牌
    稳定性 : 支持 Swup 导航
           : 验证响应式和无障碍输出

用户旅程

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

journey
    accTitle: 读者理解技术文章的过程
    accDescr: 读者发现一篇文章，通过结合正文和图表理解内容，然后继续探索相关主题。
    title 读者理解技术文章的过程
    section 发现
      浏览文章列表: 4: Reader
      选择主题: 5: Reader
    section 理解
      阅读文章: 4: Reader
      查看关系图: 5: Reader
    section 继续探索
      打开相关文章: 4: Reader
      收藏页面: 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,Topics,210
Reading,Outbound,140

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

Markdown 扩展功能

2024-05-01T00:00:00.000Z

GitHub 仓库卡片

你可以添加指向 GitHub 仓库的动态卡片。页面加载时，系统会从 GitHub API 获取仓库信息。

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

使用 ::github{repo="/"} 创建 GitHub 仓库卡片。

::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
突出显示即使快速浏览时也值得注意的信息。
:::

:::tip
帮助读者更顺利完成任务的可选信息。
:::

自定义标题

提示容器的标题可以自定义。

:::note[我的自定义标题] 这是一个带有自定义标题的说明容器。 :::

:::note[我的自定义标题]
这是一个带有自定义标题的说明容器。
:::

GitHub 语法

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

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

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

剧透内容

你可以在文本中添加剧透内容。剧透文本也支持 Markdown 语法。

内容 :spoiler[已隐藏啦]！

内容 :spoiler[已隐藏 **啦**]！

图片宽度与说明文字

独立图片的 alt 文本中可以包含可选的 w-N% 宽度标记；Markdown 标题则会显示为图片下方居中的说明文字：

![图片说明 w-50%](./image.webp "显示的说明文字")

有效宽度范围为 w-1% 至 w-100%；无效标记会保留在 alt 文本中。宽度和说明文字相互独立——仅填写标题也会显示说明文字：

Expressive Code 示例

2024-04-10T00:00:00.000Z

本文将介绍如何使用 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')


File name comment example

终端框架

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

将较长标签单独放在一行

// labeled-line-markers.jsx

使用类似 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 示例

2023-10-01T00:00:00.000Z

一级标题

段落之间以空行分隔。

这是第二段。可以使用斜体、粗体和 等宽字体。无序列表如下：

第一项
第二项
第三项

注意：不包括星号在内，正文从缩进 4 列的位置开始。

引用块的写法如下。

需要时，引用块也可以包含多个段落。

使用三个短横线表示破折号。使用两个短横线表示范围（例如“详见第 12--14 章”）。三个句点 ... 会转换为省略号。支持 Unicode 字符。☺

二级标题

有序列表示例如下：

第一项
第二项
第三项

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

# 再强调一次……
for i in 1 .. 10 { do-something(i) }

如你所料，这段代码缩进了 4 个空格。除此之外，也可以使用围栏代码块，而不必缩进整个代码块：

define foobar() {
    print "欢迎来到风味之乡！";
}

（这种写法更便于复制和粘贴。）也可以为围栏代码块指定语言，让 Pandoc 为其添加语法高亮：

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

三级标题

下面是一个嵌套列表：

首先，准备以下材料：
- 胡萝卜
- 芹菜
- 小扁豆
烧一些水。

将所有材料放入锅中，并按以下步骤操作：

 找一把木勺
 揭开锅盖
 搅拌
 盖上锅盖
 将木勺小心地架在锅柄上
 等待 10 分钟
 返回第一步（或完成后关闭炉火）

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

再次注意，正文始终与 4 个空格的缩进对齐（包括上方延续第 3 项内容的最后一行）。

链接示例：网站、本地文档和本文章节标题。这里还有一个脚注^1。

表格可以这样编写：

尺寸材质颜色

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

表格：鞋子的尺寸与材质

（上方文字是表格标题。）Pandoc 也支持多行表格：

关键词说明

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

绿色树叶、青草、青蛙，以及其他呈绿色的事物。

下面是一条水平分隔线。

下面是一个定义列表：

苹果 : 适合用来制作苹果酱。橙子 : 一种柑橘类水果！西红柿 : tomato 这个词末尾没有字母“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* 等。

在文章中嵌入视频

2023-08-01T00:00:00.000Z

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

---
title: 在文章中嵌入视频
published: 2023-10-19
// ...
---

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"}

Lambent's Blog

Shirone 编写与使用指南

1. 创建新文章

2. Frontmatter 规范

示例

支持的 Frontmatter 字段

3. 文章加密

4. 组织文章文件

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

单文件结构（适用于简短文章）

5. 丰富的 Markdown 和 MDX 扩展

5.1 提示容器

5.2 GitHub 仓库卡片

5.3 Expressive Code 代码块

5.4 数学公式排版（KaTeX）

5.5 Mermaid 图表

5.6 图片画廊与 Fancybox 灯箱

6. 后续步骤与自定义

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

Shirone Markdown 扩展功能

文件树

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

编写规则与标记

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

配置选项

代码树

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

配置与标记

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

Audio Reader：日系动画神秘语音集

语音片段

Markdown 折叠面板

独立面板

手风琴模式

编写语法

Markdown 缩写词

正文示例

定义术语

编写规则

Markdown 文件包含

Markdown 标记高亮

默认强调

语义颜色

编写语法

Markdown 选项组

选择包管理器

运行项目

多个备选项

编写语法

Markdown 剧透内容

行内详情

编写语法

Markdown 提示容器

语义变体

可选详情

编写语法

内容注释

基本语法

丰富内容

多条注释

Markdown 步骤流

有序列表语法

选项

MDX 集成与 M3E 原子组件

1. Markdown 与 MDX 功能对比

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

3. M3E Display and Layout Primitives (SSR-Only)

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

6.1 GitHub 仓库卡片

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` 处理极端比例