蓝色大肥鱼

文章加密与密码保护演示

Thu, 20 Aug 2026 00:00:00 GMT

受密码保护的文章

恭喜！你已成功解锁这篇加密文章。浏览器使用 Web Crypto API（AES-256-GCM + PBKDF2） 在本地解密了这份预先编译好的内容。

1. 安全架构与核心特性

Shirone 的文章加密系统与受保护的相册共用同一套安全基础，为静态发布提供了企业级的安全能力：

静态 HTML 构建产物中零明文
在 Astro SSG 构建流程中，文章 Markdown 会被编译为 HTML，并在输出页面前立即以 AES-256-GCM 加密。发布出去的静态 HTML 中，受保护正文与大纲不含任何明文。
带 AAD 作用域绑定的认证加密
- 密钥派生遵循 OWASP 建议，使用 310,000 次 PBKDF2 迭代（SHA-256）与一个密码学安全的 16 字节随机盐；
- 每一份加密载荷都会生成独立的 12 字节随机 IV；
- 附加认证数据（AAD） 绑定 shirone-protected-content:1:post:${slug}，确保密文无法在不同文章或相册之间被重放。
会话保持与磁盘零密码存储
- 解密后的内容缓存在浏览器临时会话存储中，30 分钟后过期；
- 明文密码绝不会写入磁盘或存储；
- 在同一会话内，解密状态可无缝跨越 Swup 客户端导航与页面刷新。
全站防泄漏
- 搜索索引：静态页面不含明文，搜索引擎与 Pagefind 都无法索引私密内容；
- RSS 订阅：受保护文章在订阅源中输出本地化占位内容，避免 RSS 聚合器抓取敏感文本；
- 卡片摘要与字数：配置 hideHomeContent: true 后，列表页与归档卡片的描述和字数会被遮蔽；
- 目录（TOC）：解锁前标题层级保持隐藏，解密后再动态重建并与 M3E 样式同步。

💡 演示说明：本篇演示文章的默认解锁密码是 shirone-secret。

2. 交互式富内容演示

文章解密后会与运行时辅助模块协同，动态挂载语法高亮、代码折叠、可交互的 Mermaid 图表、LaTeX 公式与图片灯箱。

2.1 代码块与语法高亮

下面的代码块用于检验 Expressive Code 的语法高亮、复制操作与行装饰：

import { decryptProtectedContent, type ProtectedPayload } from "@/utils/password-protection";

/**
 * 客户端文章解密示例
 */
async function unlockArticle(payload: ProtectedPayload, password: string): Promise<string> {
    const scope = payload.scope;
    console.log(`[Shirone] Decrypting scope: ${scope}`);
    
    // 执行带 AAD 校验的 AES-256-GCM 解密
    const decryptedHtml = await decryptProtectedContent(payload, password, scope);
    console.log("[Shirone] Decryption successful, length:", decryptedHtml.length);
    return decryptedHtml;
}

# 校验构建与类型检查
npx.cmd astro check
pnpm.cmd type-check
pnpm.cmd test

2.2 Mermaid 架构图

下面的流程图由 Mermaid 渲染，并在解密时动态绑定：

flowchart TD
    subgraph build["构建流水线"]
        A[Markdown 源码] --> B[Astro 流水线]
        B --> C[渲染 HTML]
        C --> D[encryptProtectedContent]
        D --> E[ProtectedPayload]
        E --> F[含 ProtectedPost 的静态 HTML]
    end

    subgraph runtime["客户端运行时"]
        G[读者访问页面] --> H{会话是否有效？}
        H -->|是| K[渲染解密后的 HTML]
        H -->|否| I[显示 PasswordGate]
        I --> J[用户提交密码]
        J --> L[Web Crypto AES-GCM 解密]
        L -->|失败| M[给出错误反馈]
        L -->|成功| N[写入会话记录]
        N --> K
        K --> O[触发解密后协调器]
        O --> P[初始化复制、Mermaid、KaTeX 与目录]
    end

2.3 LaTeX 数学公式

行内公式：欧拉恒等式 $e^{i\pi} + 1 = 0$ 与高斯积分 $\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$。

块级公式会带有横向滚动容器：

$$ f(x) = \frac{1}{\sigma \sqrt{2\pi}} \exp\left( -\frac{(x - \mu)^2}{2\sigma^2} \right) $$

$$ \mathcal{L}_{\text{AES-GCM}} = \text{GHASH}_H(A \parallel C \parallel L) \oplus \text{AES}_K(J_0) $$

2.4 提示块

:::note 架构说明这套加密系统遵循原子化设计原则与最小补丁约定，同时不牺牲 SSR 稳定性。 :::

:::tip 主题集成解锁后可以试试在明暗模式之间切换，或更改主色相；解密出来的组件会动态适配当前生效的设计令牌。 :::

:::important 安全边界静态客户端加密用于阻止未授权浏览与自动化索引。对于性命攸关的商业机密，建议改用服务端鉴权。 :::

:::warning 密码找回静态加密没有集中式服务端数据库。一旦忘记密码，加密内容将无法恢复。 :::

2.5 GitHub 仓库卡片

::github{repo="withastro/astro"}

3. 配置参考

参数	类型	是否必填	默认值	说明
`encrypted`	`boolean`	否	`false`	显式标记该文章为加密文章。若设置了 `password`，则隐含为 `true`。
`password`	`string`	是	无	构建时用于加密、运行时用于解锁的明文密码。
`passwordHint`	`string`	否	`""`	可选提示，显示在密码输入框下方。
`hideHomeContent`	`boolean`	否	`true`	在列表卡片、归档与 RSS 订阅中隐藏文章描述与字数统计。

4. 小结

本次演示验证了 Shirone 完整的加密生命周期：静态产物零明文、可靠的密码学校验、会话在导航与刷新之间的持续保持，以及运行时对富内容的动态重建。

Shirone Markdown 扩展

Wed, 19 Aug 2026 00:00:00 GMT

Shirone 提供了一组主题专属的 [[Markdown]] 扩展与自定义语法容器。它们构建在我们原生 unified AST 处理管线之上。

想了解这套管线为什么「零注水」，可以看 [[Astro]] 的岛架构说明。

Shirone 提供了一组主题专属的 Markdown 扩展与自定义语法容器。它们构建在我们原生 unified AST 处理管线之上，所有扩展都在站点构建期渲染为无障碍且语义化的 HTML，不产生任何客户端 JavaScript 注水开销，并完全对齐 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 :::

写作规则与标记

差异状态：给条目前加 ++（绿色背景与徽标）或 --（红色背景与删除线）即可高亮变更。
注释：# 之后的文本会渲染为淡色、右对齐的行内注释。
强调：用 **粗体** 包裹名称，让关键文件获得更醒目的视觉权重。
可折叠目录：由嵌套列表项推断出的目录默认展开。加上结尾斜杠（如 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"

我的一些小工具

Mon, 12 Oct 2026 16:01:21 GMT

三、纯文本笔记

[[Markdown]] 文件 + 一个文件夹，比任何笔记软件都可靠。

工具越少，折腾越少。顺带一提：这个站的正文就是 [[Astro]] 构建期渲染出来的。

我的一些小工具

记录几个每天都在用、但很少被提起的小工具。

一、截图

系统自带 + 一个标注工具就够，不用装大而全的。

二、剪贴板历史

用过就回不去了 —— 尤其是写代码的时候。

三、纯文本笔记

Markdown 文件 + 一个文件夹，比任何笔记软件都可靠。

工具越少，折腾越少。

胶片摄影入门：我踩过的五个坑

Mon, 12 Oct 2026 15:58:54 GMT

拍完就扔抽屉里

最重要的是：多拍。

拍照之余我也写点前端笔记，比如 [[Vite]] 和 [[Docker]] 的入门整理。

五个坑

以为胶片一定比数码好看
不看 ISO 就买卷
冲扫店随便选
不记曝光参数
拍完就扔抽屉里

最重要的是：多拍。

本周读到的三篇好文

Mon, 12 Oct 2026 15:58:54 GMT

本周阅读

一、关于专注

深度工作这件事，说的人多，做的人少。

二、关于写作

写不出来的时候，先写最烂的一版。

三、关于工具

工具会过时，习惯不会。

CSS Grid 实战：一个两栏布局的三种写法

Mon, 12 Oct 2026 15:58:53 GMT

3. grid（推荐）

.layout {
  display: grid;
  grid-template-columns: 16rem 1fr;
}

语义最清楚，改起来也最方便。

这套布局方式在 [[Vite]] 的开发服务器里也用到了（它的 HMR 客户端就靠固定两栏）。

三种写法

1. float（不推荐）

需要清浮动，还要自己算宽度。

2. flex

一行搞定，但等宽分栏要写 flex: 1。

3. grid（推荐）

.layout {
  display: grid;
  grid-template-columns: 16rem 1fr;
}

语义最清楚，改起来也最方便。

新人报到：我为什么开始写博客

Mon, 12 Oct 2026 15:58:53 GMT

前端工程化的一些踩坑记录 ← 打算从 [[Vite]] 与 [[ES 模块]] 讲起
[[TypeScript 泛型]] 也是我一直想系统写一写的东西

为什么写博客

断断续续用过大大小小好几个笔记软件，最后还是觉得自己的站点最踏实。

打算写什么

前端工程化的一些踩坑记录
摄影相关的随笔
偶尔的碎碎念

先把站搭起来，内容慢慢填。

【MySQL 数据源验证】这篇文章只存在于数据库

Thu, 08 Oct 2026 12:00:00 GMT

验证成功

这篇文章不存在于任何 Markdown 文件，只存在于 bluefish_blog.post 表。

能看到它，就证明 Astro 的数据源已经切换成 MySQL。

音频朗读：日系动画里的神秘人声

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 地址，且指令标签不能为空。无效或不完整的指令会保留为普通 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。浏览器会直接对原生折叠元素分组，因此展开另一项时会自动收起上一项，全程无需水合。

::: collapse accordion expand

这里的 expand 起什么作用？

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

可以。标题支持行内强调与 代码，而面板正文支持完整的块级 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]: Server-Side Rendering *[LCP]: Largest Contentful Paint *[CLS]: Cumulative Layout Shift

写作边界

术语必须以字母或数字开头，并且可以包含字母、数字、句点、下划线、加号与连字符。每条定义只对当前文章生效；无效或重复的定义会保持为普通 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} -->

围栏代码块内部的包含注释会保持字面原样。

Markdown 标记高亮

Fri, 28 Aug 2026 00:00:00 GMT

标记高亮可以把注意力引向某个具体语句，而不必把周围的段落单独做成一个组件。它们在构建期渲染为原生的 <mark> 元素，并继承当前生效的 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}

诸如 ==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#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 需要中性补充信息帮助读者理解上下文时，使用 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] 真正需要交互时才对其进行水合。

[+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[生产环境部署]

克隆并准备工作区

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

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 或网络请求。

Shirone 写作与使用指南

Wed, 26 Aug 2026 00:00:00 GMT

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

站点本身用 [[Astro]] 构建 —— 静态输出、零客户端 JavaScript 注水，构建流程细节见 [[Vite]] 相关笔记。

欢迎使用 Shirone（白音）——一款围绕 Astro 7、Svelte 5 与 Material 3 Expressive（M3E） 设计体系打造的表现力强、二次元气质的博客主题。

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

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

1. 创建新文章

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

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

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

新创建的文件会被放入 src/content/posts/。

2. Frontmatter 规范

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

示例

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

支持的 Frontmatter 字段

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

3. 文章加密

Shirone 提供客户端文章加密。这是一个静态的密码门禁，而非服务端访问控制：加密后的正文载荷与资源 URL 仍可被公开下载，因此请勿将它用于真正机密的文件或受监管的敏感信息。对于私密日记或限定访问的文章，可在 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           <-- 文章内容
│   ├── 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("Primary color token:", theme.schemes.light.primary);

5.4 数学排版（KaTeX）

直接在 Markdown 中渲染优雅的 LaTeX 数学记号：

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

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

5.5 Mermaid 图表

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

sequenceDiagram
    autonumber
    actor Visitor as 访客
    participant Page as 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 分享你的想法与疑问。

MDX 集成与 M3E 原子组件

Thu, 20 Aug 2026 00:00:00 GMT

这个页面演示如何在 MDX 里直接使用 [[TypeScript 泛型]] 风格的类型注解与组件 props。

:::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 展示类原子	不可用	直接集成（``、`<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> </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 源文件] --> Compiler["@astrojs/mdx 编译器"]
    Compiler --> Plugins["Remark / Rehype SSOT 管线"]
    Plugins --> Islands["Svelte 5 交互岛"]
    Islands --> Swup["Swup 客户端导航外壳"]
    Swup --> Screen["M3E 表现力文章视图"]

6.3 数学表达式（LaTeX / KaTeX）

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

块级公式：

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

7. 小结

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

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

Mon, 13 Jul 2026 00:00:00 GMT

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

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

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

最简语法

把 Markdown 图片直接写在 :::grid 与结束的 ::: 之间：

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

![图片说明](./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"}
![第一张图](./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 设为接近原图的比例，或让该图片独占一个网格。

下面的示例把同样的竖向图片分别放入 cover 与 contain 的 16/9 卡片中。前者会裁切，后者保留完整图片并留下背景空间。

:::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 图表合集

Thu, 02 May 2024 00:00:00 GMT

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 : uses
    DiagramRenderer --> MermaidPlugin : enhances output
    DiagramRenderer --> ThemeTokens : reads

状态图

状态图展示一个对象在生命周期内的各种状态，以及推动状态迁移的事件。

stateDiagram-v2
    accTitle: 文章生命周期
    accDescr: 文章从草稿走到审核与发布，可能被退回修改，最终也可能归档。
    [*] --> Draft
    Draft --> InReview : submit
    InReview --> Draft : request changes
    InReview --> Published : approve
    Published --> Draft : retract
    Published --> Archived : archive
    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 扩展特性

Wed, 01 May 2024 00:00:00 GMT

GitHub 仓库卡片

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

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

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

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

Mermaid 图表

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

flowchart LR
    accTitle: Markdown 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[MY CUSTOM TITLE] 这是一条带自定义标题的 note。 :::

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

GitHub 语法

[!TIP] 也支持 GitHub 的语法。

> [!NOTE]
> 也支持 GitHub 的语法。

> [!TIP]
> 也支持 GitHub 的语法。

剧透

你可以为文字添加剧透。其中的文字同样支持 Markdown 语法。

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

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

图片宽度与说明文字

独立图片的替代文本中可带一个可选的 w-N% 宽度标记，而 Markdown 标题会渲染为图片下方居中的说明文字：

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

有效宽度范围是 w-1% 到 w-100%；无效标记会保留在替代文本中。宽度与说明文字相互独立——只写标题同样会产生说明文字：

Expressive Code 示例

Wed, 10 Apr 2024 00:00:00 GMT

下面来看看使用 Expressive Code 时，代码块会呈现出怎样的效果。文中的示例取自官方文档，需要更多细节可以查阅该文档。

Expressive Code

语法高亮

Syntax Highlighting

常规语法高亮

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

编辑器与终端外框

Editor & Terminal Frames

代码编辑器外框

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

# 若不覆盖外框类型，这里原本会渲染成终端外框
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

文本与行标记

Text & Line Markers

标记整行与行范围

// 第 1 行 —— 由行号定位
// Line 2
// Line 3
// 第 4 行 —— 由行号定位
// Line 5
// Line 6
// 第 7 行 —— 由范围 "7-8" 定位
// 第 8 行 —— 由范围 "7-8" 定位

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

function demo() {
  console.log('this line is marked as deleted')
  // 这一行与下一行被标记为新增
  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() {
    // 整个代码块按 JavaScript 高亮，
    // 同时依然可以为它添加 diff 标记！
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }

标记行内的个别文本

function demo() {
  // 标记行内任意指定的文本
  return 'Multiple matches of the given text are supported';
}

正则表达式

console.log('单词 yes 与 yep 会被标记出来。')

转义正斜杠

echo "Test" > /home/test.txt

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

function demo() {
  console.log('These are inserted and deleted marker types');
  // return 语句使用默认的标记类型
  return true;
}

自动换行

Word 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'
}

// 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'
}

配置折行后的缩进

// preserveIndent 的示例（默认启用）
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'
}

// 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'
}

可折叠区块

Collapsible Sections

// 这一整段样板初始化代码都会被折叠
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// 这部分代码默认可见
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // 可以设置多个折叠区块
  const a = 1
  const b = 2
  const c = a + b

  // 这部分保持可见
  console.log(`Calculation result: ${a} + ${b} = ${c}`)
  return c
}

// 从这里到代码块结束的部分会再次折叠
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })

行号

Line Numbers

为单个代码块显示行号

// 这个代码块会显示行号
console.log('Greetings from line 2!')
console.log('I am on line 3')

// 该代码块已关闭行号
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

一级标题

段落之间用空行分隔。本页演示的是标准 [[Markdown]] 语法，站点渲染管线见 [[Astro]]。

一级标题

段落之间用空行分隔。

第二段。斜体、粗体与 等宽字体。无序列表长这样：

这一项
那一项
另一项

注意 --- 这里不涉及星号 --- 实际文本内容是从第 4 列开始的。

引用块就是这样写的。

如果需要，它们可以跨越多个段落。

用三个连字符表示破折号。用两个连字符表示范围（例如"it's all in chapters 12--14"）。三个点 ... 会被转换成省略号。Unicode 也能正常显示。☺

二级标题

这是一个有序列表：

第一项
第二项
第三项

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

# Let me re-iterate ...
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

三级标题

现在来看嵌套列表：

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

把所有东西倒进锅里，然后按下面的算法操作：

 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 : Good for making applesauce. oranges : Citrus! tomatoes : There's no "e" in tomatoe.

同样，文本缩进了 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* 等。

在文章中嵌入视频

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

蓝色大肥鱼

文章加密与密码保护演示

受密码保护的文章

1. 安全架构与核心特性

2. 交互式富内容演示

2.1 代码块与语法高亮

2.2 Mermaid 架构图

2.3 LaTeX 数学公式

2.4 提示块

2.5 GitHub 仓库卡片

3. 配置参考

4. 小结

Shirone Markdown 扩展

文件树

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

写作规则与标记

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

配置项

代码树

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

配置与标记

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

我的一些小工具

三、纯文本笔记

我的一些小工具

一、截图

二、剪贴板历史

三、纯文本笔记

胶片摄影入门：我踩过的五个坑

五个坑

本周读到的三篇好文

本周阅读

一、关于专注

二、关于写作

三、关于工具

CSS Grid 实战：一个两栏布局的三种写法

3. grid（推荐）

三种写法

1. float（不推荐）

2. flex

3. grid（推荐）

新人报到：我为什么开始写博客

为什么写博客

打算写什么

【MySQL 数据源验证】这篇文章只存在于数据库

验证成功

音频朗读：日系动画里的神秘人声

片段一览

Markdown 折叠面板

独立面板

手风琴模式

作者语法

Markdown 缩写词

上下文示例

定义术语

写作边界

Markdown 文件包含

Markdown 标记高亮

默认强调

语义配色

作者语法

Markdown 选项组

选择包管理器

运行项目

更多备选

作者语法

Markdown 剧透

行内细节

作者语法

Markdown 提示块

语义变体

可选详情

作者语法

内容注解

基础语法

富文本内容

多重定义

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`