本指南将带你了解文章创建、前置元数据规范、目录结构，以及全套内置 Markdown 和 MDX 扩展。

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

1. 创建新文章

你可以使用内置 CLI 命令快速创建一个带标准前置元数据的新文章：

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

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

新创建的文件将放置在 src/content/posts/ 中。

2. 前置元数据规范

每个 Markdown（.md）或 MDX（.mdx）文章都以 YAML 前置元数据块开头，用于定义其元数据。

示例

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

支持的前置元数据字段

3. 文章加密

Shirone 提供客户端文章加密。这是一个静态密码门禁，而非服务端访问控制：加密载荷和资源 URL 仍然可以被公开下载，因此请勿将其用于真正机密的文件或受监管的敏感信息。对于私密日记或受限文章，请在前置元数据中指定密码：

---
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           <-- 文章内容
│   ├── cover.webp         <-- 封面图片（image: "./cover.webp"）
│   └── diagram.png        <-- Markdown 中引用的内嵌插图

单文件结构（轻量散文）

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

5. 丰富的 Markdown 与 MDX 扩展

Shirone 开箱即包含现代 Markdown 扩展：

5.1 提示块（Admonitions）

使用容器指令表示笔记、提示、警告和警报：

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

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

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 上分享你的想法和问题。

文件树

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

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 源代码树"}

• 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="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 组件演示" 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="动漫工具" entry="status.ts"

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

音频朗读器会保持安静，直到你选择聆听。每个扬声器按钮只有在被按下后才会加载并播放其片段。

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

独立面板

默认情况下，各项独立展开。在标题前加上 :+ 可使该项初始展开，或加上 :- 可在分组使用 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 列表。

在上下文中

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]: Server-Side Rendering *[LCP]: Largest Contentful Paint *[CLS]: Cumulative Layout Shift

创作边界

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

<!-- @include: src/content/snippets/include-example.md#public-api -->

也支持完整文件和行范围两种形式：

<!-- @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 强调==。

语义颜色

当含义需要不同的色调角色时，使用后缀。可用的变体有 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}

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

选择包管理器

使用 @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 Local workstation

在开发功能时使用本地工具链。

@tab Hosted preview environment

发布临时预览以供审核。

@tab Continuous integration

为每次更改运行确定性验证。

@tab Production deployment

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

@tab Offline recovery workflow

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

:::

作者语法

::: tabs#package-manager

@tab npm

Use npm instructions here.

@tab:active **pnpm**#pnpm

Use pnpm instructions here.

:::

每个组至少需要两个 @tab 部分，并且每个部分都需要正文内容，正文与其标记之间用空行分隔。无效或不完整的组将保持为普通 Markdown 的可读形式。

Inline details

The answer is :spoiler[42], and this sentence remains ordinary Markdown around it.

Spoilers can include inline code and :spoiler[a longer detail with emphasis].

Author syntax

The answer is :spoiler[42].

The generated HTML uses a native button with an aria-expanded state. Without JavaScript, hover and focus still reveal the text; the optional runtime adds click and keyboard toggling.

语义变体

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

:::info 使用信息块来提供中性的上下文，帮助读者理解周围章节。 :::

:::tip[现有的 标签 语法] 原有的方括号标签仍然可用，并且可以包含行内 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.
:::

基本语法

在普通行文中添加 [+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 有序列表包裹在 :::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[生产部署]

1. 克隆并准备工作区

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

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

2. 安装依赖

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

   pnpm.cmd install
   

3. 运行项目检查

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

   npx.cmd astro check
   pnpm.cmd type-check
   

4. 构建生产站点

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

   pnpm.cmd build
   

:::

选项

• :::steps[Title] 或 title="Title" 添加可见标签和可访问名称。
• start=4 更改第一个显示的步骤编号。
• 该容器必须恰好包含一个有序列表。无效或混合的输入将保持为普通的可读 Markdown，而不会被启发式地解释。
• 渲染在站点构建期间完成，不添加任何客户端 JavaScript 或网络请求。

1. Markdown 与 MDX 能力对比矩阵

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">Filled Card</div> <div class="text-sm text-[var(--on-surface-variant)]">Default container background with no elevation shadow. Ideal for grouped content blocks.</div>

<div class="font-bold text-[var(--primary)] mb-2">Elevated Card</div>
<div class="text-sm text-[var(--on-surface-variant)]">Level 1 container elevation with interactive state layering for heightened visual focus.</div>



<div class="font-bold text-[var(--primary)] mb-2">Outlined Card</div>
<div class="text-sm text-[var(--on-surface-variant)]">A crisp 1px outline boundary providing clean separation on neutral surfaces.</div>

</div>

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

<div class="flex items-center gap-4 my-4 p-4 rounded-lg bg-[var(--surface-container-high)]">

<div class="flex-1"> <span class="font-bold text-lg">System Announcement</span> <p class="text-xs text-[var(--on-surface-variant)] m-0">Combine AccentBar with Badge to build prominent visual callouts</p> </div> M3E v0.192 </div>

3.3 骨架占位符（Skeleton.svelte）

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

<div class="flex flex-col gap-3 my-6 p-5 rounded-xl border border-[var(--outline-variant)] bg-[var(--surface-container-low)]"> <div class="flex items-center gap-3">

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

</div>

</div>

4. 反馈与加载指示器

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

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

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

<div class="grid grid-cols-1 md:grid-cols-3 gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)] text-center"> <div class="flex flex-col items-center gap-2"> <div class="h-16 flex items-center justify-center">

</div>
<span class="text-xs text-[var(--on-surface-variant)]">Indeterminate Shape Morph</span>

</div>

<div class="flex flex-col items-center gap-2"> <div class="h-16 flex items-center justify-center">

</div>
<span class="text-xs text-[var(--on-surface-variant)]">Contained Circular Variant</span>

</div>

<div class="flex flex-col items-center gap-2"> <div class="h-16 flex items-center justify-center">

</div>
<span class="text-xs text-[var(--on-surface-variant)]">Determinate Progress (68%)</span>

</div> </div>

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

<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 flex-col gap-2"> <div class="flex justify-between text-xs text-[var(--on-surface-variant)]"> <span>Pipeline Compilation</span> <span>80%</span> </div>

</div>

<div class="flex flex-col gap-2 mt-2"> <div class="text-xs text-[var(--on-surface-variant)]">Continuous Dual-Line Animation</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)]"> Filled Button Elevated Tonal Button Outlined Text Button </div>

5.2 筛选标签与分段按钮（Chips 与 SegmentedButton）

<div class="flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]"> <div> <div class="text-xs font-bold text-[var(--on-surface-variant)] mb-2">M3E Filter Chips</div>

</div>

<div> <div class="text-xs font-bold text-[var(--on-surface-variant)] mb-2">Segmented Control</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">Switch with Status Icons</span>

</div>

<div class="flex items-center justify-between"> <span class="font-bold text-sm">Selection Checkboxes</span> <div class="flex items-center gap-4">

</div>

</div>

<div class="flex flex-col gap-2"> <span class="font-bold text-sm">Hue Spectrum Slider</span>

</div> </div>

5.4 输入控件（TextField.svelte）

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">

</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 令牌设计系统，确保一致性、无障碍性和视觉和谐。

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

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

最小语法

直接在 :::grid 和闭合的 ::: 之间编写 Markdown 图片：

:::grid
![图片描述](./image-1.webp)

![图片描述](./image-2.webp)
:::

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

以下是最小语法的结果。在不带参数的情况下，网格默认使用三列、16/10 比例和 cover。

:::grid

:::

参数概览

所有参数写在开始指令后的花括号中：:::grid{参数="值"}。

完整示例：

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

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

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

以下结果是使用上述三列横图语法的效果。比较卡片比例、列数，以及标题优先于替代文本作为说明文字的方式：

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

:::

标题与替代文本

图片的替代文本既可用作无障碍替代文字，也可用作默认标题。当图片带有可选标题时，将使用标题作为说明文字：

![用于无障碍的文字](./image.webp "显示在图片下方的标题")

在同一行中，标题对齐到每张卡片的底部。换行的标题不会使其他标题浮动在不同的高度。比例文本如 3:4 和 16:9 可以直接写在正文、标题和替代文本中，无需转义。

此示例演示了默认的替代文本标题、显式标题标题，以及较长标题的底部对齐效果：

:::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 图片仍会被单独处理；它们不会被添加到任何画廊网格中。

检查清单

1. 每个网格中的图片具有一致的尺寸，标题位于卡片下方。
2. 悬停时图片轻微缩放；点击后可使用键盘缩放、旋转和导航。
3. 点击“16:9 测试图一”时，灯箱仅浏览该部分中的另外两张横图。
4. 低于 768px 时，网格最多使用两列；低于 480px 时，使用一列。
5. “四列配合 contain”中的竖图完全可见，留有空白且无裁剪。
6. 五列和六列网格在宽屏上保持指定的列数，然后根据响应式规则折叠为两列或一列。

流程图

流程图描述一个过程，包括决策以及返回先前步骤的路径。

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]

时序图

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

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 导航到本文时，图表会重新渲染。

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

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

使用代码 ::github{repo="<owner>/<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[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[是隐藏的 哎哟]！

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

图片宽度与标题

独立图片可以在其替代文本中接受可选的 w-N% 宽度标记，并将 Markdown 标题渲染为图片下方居中的说明文字：

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

有效宽度范围从 w-1% 到 w-100%；无效标记会保留在替代文本中。宽度和说明文字是独立的——仅提供标题也会生成说明文字：

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')

段落之间用空行分隔。

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

• 这一项
• 那一项
• 另一项

请注意——不考虑星号——实际文本内容从第 4 列开始。

引用是这样 写的。

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

使用 3 个短横线表示破折号。使用 2 个短横线表示范围（例如，“it's all in chapters 12--14”）。三个点 ... 会被转换为省略号。支持 Unicode。☺

一个 h2 标题

这是一个编号列表：

1. 第一项
2. 第二项
3. 第三项

再次注意实际文本是如何从第 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

一个 h3 标题

现在是一个嵌套列表：

1. 首先，准备这些食材：

   • 胡萝卜
   • 芹菜
   • 扁豆

2. 煮一些水。

3. 把所有东西倒进锅里，然后按照 这个算法操作：

    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。

表格可以看起来像这样：

size material color

9 leather brown 10 hemp canvas natural 11 glass transparent

Table: Shoes, their sizes, and what they're made of

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

keyword text

red Sunsets, apples, and other red or reddish things.

green Leaves, grass, frogs and other things it's not easy being.

接下来是一条水平分隔线。

这是一个定义列表：

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

再次说明，文本缩进了 4 个空格。（在每个术语/定义对之间放一个空行，可以让内容更分散。）

这是一个“行块”：

| Line one | Line too | Line tree

图片可以这样指定：

行内数学公式这样写：$\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* 等。

---
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 video" preload="auto"}

Bilibili

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

AcFun

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

ArtPlayer

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