二甲基

音频朗读条

Fri, 16 Oct 2026 00:00:00 GMT

音频朗读条（Audio Reader）允许在正文中为特定词句或短语插入行内发音、有声朗读或音频试听按钮。

语法格式

使用 :audio-reader 文本指令并传入音频文件地址 src：

日语中「ありがとう」的读音为 :audio-reader[发音示范]{src="/assets/audio/arigatou.mp3"}。

渲染效果（本站示例音频位于 public/assets/music/url/）：

日语中「ありがとう」的读音为 :audio-reader[发音示范]{src="/assets/music/url/cl.mp3"}。

点击徽章即可播放对应片段。

放在句子中间

audio-reader 是纯行内语法，可以与文字、高亮、行内代码自由混排：

这个词在英式英语中读作 :audio-reader[英音]{src="/assets/audio/en-uk.mp3"}，
在美式英语中读作 :audio-reader[美音]{src="/assets/audio/en-us.mp3"}。

与其它音频方案的取舍

方案	语法	适用场景
行内朗读条	`:audio-reader[文字]{src="..."}`	单词发音、短句示范
HTML5 音频	`<audio controls src="...">`	独立成段的完整音频
ArtPlayer	`::artplayer{...}`	需要播放控制的音频流

短发音用 :audio-reader，读者不需要离开阅读动线。
整段音频（播客、音乐）建议用艺术播放器或原生 <audio> 标签单独成段。

交互效果

正文中呈现为精巧的发音波形微徽章。
点击后播放对应音频片段，并带有声波跳动视觉反馈。
采用原生 Web Audio API 与 HTML5 Audio，轻量流畅。

::: tip 音频资源建议朗读类音频通常只有几十到几百 KB，适合与文章一起放在 public/ 目录中。若音频文件较大，请确认 preload 行为不会在页面加载时抢占带宽——audio-reader 只在点击后才请求音频。 :::

ArtPlayer 播放器

Thu, 15 Oct 2026 00:00:00 GMT

ArtPlayer 播放器组件用于播放自托管的本地视频文件或第三方直链媒体资源（支持 MP4、WebM 与 HLS 流媒体）。

语法格式

使用 ::artplayer 指令并配置参数：

::artplayer{src="/videos/demo.mp4" title="本地示例视频" poster="/assets/poster.webp" preload="auto"}

渲染效果（下例使用公开的 CC0 测试视频）：

::artplayer{src="https://mdn.github.io/shared-assets/videos/flower.mp4" title="ArtPlayer 演示视频" poster="/assets/projects/shirone.webp" preload="auto"}

属性参数列表

属性名	类型	是否必填	默认值	说明
`src`	`string`	必填	无	视频直链地址或相对 `/public` 的本地路径
`title`	`string`	必填	无	视频标题
`poster`	`string`	可选	无	未播放时的封面海报图片路径
`preload`	`string`	可选	`"none"`	预加载策略：`"none"`（默认）或 `"auto"`（视口临近预加载）

播放自托管视频

把视频文件放进内容仓库的 public/videos/ 目录，再用绝对路径引用：

::artplayer{src="/videos/demo.mp4" title="本地示例视频" poster="/assets/poster.webp"}

::: file-tree{title="推荐的目录结构"}

public/
- videos/
  - demo.mp4
- assets/
  - poster.webp :::

路径写法	指向
`/videos/demo.mp4`	内容仓库 `public/videos/demo.mp4`
`https://example.com/stream.m3u8`	外部 HLS 流

::: warning 大文件与构建 public/ 下的文件会原样拷贝进构建产物，建议只放体积可控的短片，并在发布前确认仓库不会因此膨胀。长视频更适合放在对象存储或 CDN 上，用直链嵌入。 :::

核心能力

现代播放器体验：提供精美的播放控制栏、音量调节、倍速播放、全屏与画中画模式。
动态按需加载：只有在文章中使用了 ArtPlayer 时才会异步引入播放器依赖包。
HLS 支持：直接传入 .m3u8 地址即可播放流媒体，无需额外配置。

与视频平台嵌入的分工

需求	推荐指令
自托管 MP4 / WebM	`::artplayer`
HLS 直播或点播流	`::artplayer`
B 站 / YouTube / A 站稿件	对应的平台指令

平台指令负责 Facade 占位与第三方脚本的延迟加载；当你手上有视频文件本身时，ArtPlayer 是更直接的选择。

AcFun 视频

Wed, 14 Oct 2026 00:00:00 GMT

Shirone 支持嵌入 AcFun 弹幕视频网的视频内容，支持预加载与响应式排版。

语法格式

使用 ::acfun 指令并配置参数：

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

渲染效果：

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

属性参数列表

属性名	类型	是否必填	默认值	说明
`acid`	`string`	必填	无	AcFun 视频稿件的 AC 号
`title`	`string`	必填	无	视频标题说明
`preload`	`string`	可选	`"none"`	预加载策略：`"none"`（默认）或 `"auto"`（视口临近预加载）

AC 号取自稿件链接 https://www.acfun.cn/v/ac48649632，写法上需要保留 ac 前缀。

默认占位模式

::acfun{acid="ac48649632" title="默认占位模式"}

渲染效果：

::acfun{acid="ac48649632" title="默认占位模式"}

渲染特性

采用 16:9 响应式比例，自适应缩放。
支持通过 preload="auto" 在读者视口滚动临近时提前初始化播放器。

三个视频平台指令对照

平台	指令	必填参数	参数形态
Bilibili	`::bilibili`	`bvid`	`BV` 开头的 BV 号
YouTube	`::youtube`	`id`	11 位视频 ID
AcFun	`::acfun`	`acid`	`ac` 开头的 AC 号

::: tip 统一写法三条指令的参数名不同，但都遵循「一个必填标识 + 一个标题 + 可选 preload」的结构。写文章时把平台标识和 title 一起写完，剩下的交给默认值即可。 :::

YouTube 视频

Tue, 13 Oct 2026 00:00:00 GMT

Shirone 支持嵌入 YouTube 视频，遵循严格的 Facade 占位与预加载控制规范。

语法格式

使用 ::youtube 指令并配置参数：

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

渲染效果：

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

属性参数列表

属性名	类型	是否必填	默认值	说明
`id`	`string`	必填	无	YouTube 视频链接中的 11 位唯一 ID
`title`	`string`	必填	无	视频标题描述
`preload`	`string`	可选	`"none"`	预加载策略：`"none"`（默认）或 `"auto"`（视口临近预热）

视频 ID 就是观看链接 https://www.youtube.com/watch?v=xxxxxxxxxxx 中 v= 后面的部分，也等同于短链 https://youtu.be/xxxxxxxxxxx 的路径段。

预加载与隐私策略

preload="none"：未点击前不下载 YouTube 播放器脚本与第三方 Cookie。
preload="auto"：临近视口时提前加载容器占位，提高点击后的响应速度。

::youtube{id="5gIf0_xpFPI" title="默认占位模式"}

渲染效果（默认 none）：

::youtube{id="5gIf0_xpFPI" title="默认占位模式"}

与 Bilibili 嵌入的差异

对比项	`::bilibili`	`::youtube`
必填标识	`bvid`	`id`
分 P 支持	有（`p` 参数）	无
默认预加载	`none`	`none`
点击前的外部请求	0	0

::: warning 可访问性指令中的 title 不只是海报上的文字，它会成为嵌入区域的辅助描述。请填写真实、具体的视频标题，而不要写「点击播放」这类没有信息量的文案。 :::

两个平台共用同一套 16:9 响应式容器，因此混排时卡片高度完全一致，不会破坏文章节奏。

Bilibili 视频

Mon, 12 Oct 2026 00:00:00 GMT

Shirone 提供了零额外负担的 Bilibili 视频嵌入指令，支持 Facade 占位模式与视口临近预加载机制。

语法格式

使用 ::bilibili 行级指令并配置参数：

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

渲染效果：

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

点击封面才会真正加载 B 站播放器，在此之前页面上只存在一张海报图与播放按钮。

属性参数列表

属性名	类型	是否必填	默认值	说明
`bvid`	`string`	必填	无	Bilibili 视频的 BV 号（如 `BV1fK4y1s7Qf`）
`title`	`string`	必填	无	视频标题，用于可访问性描述与海报标注
`p`	`number`	可选	`1`	分 P 编号
`preload`	`string`	可选	`"none"`	预加载策略：`"none"`（默认纯占位）或 `"auto"`（视口临近预加载）

预加载策略（preload）

preload="none"（默认）：首屏严格保持 0 请求。只渲染封面海报与播放按钮，读者手动点击后才加载播放器。
preload="auto"（视口预加载）：当视频卡片滚动进入读者视口前夕，利用交叉观察器提前初始化播放器容器与元数据，使点击播放更加即时流畅。

::bilibili{bvid="BV1fK4y1s7Qf" title="默认占位模式"}

渲染效果（默认 none）：

::bilibili{bvid="BV1fK4y1s7Qf" title="默认占位模式"}

指定分 P

一个多 P 视频可以只嵌入其中一集：

::bilibili{bvid="BV1fK4y1s7Qf" title="第二集" p=2}

响应式排版

外层容器统一锁定 16:9 标准比例，在桌面端与移动端均自适应缩放，绝不撑破文章排版。

::: tip 该用哪种 preload 教程类文章的读者点击播放的概率高，用 preload="auto" 能明显减少等待；只是「参考资料」性质的视频，保持默认 none 可以避免为一篇没人点击的文章付出网络成本。 :::

场景	建议
正文核心演示视频	`preload="auto"`
文末延伸观看	省略 `preload`（默认 `none`）
多 P 系列	按需指定 `p`

Mermaid 图表

Sun, 11 Oct 2026 00:00:00 GMT

Shirone 原生集成了 Mermaid 图表渲染引擎，支持在 Markdown 中直接绘制流程图、时序图、甘特图、类图与状态图。

流程图（Flowchart）

```mermaid
flowchart TD
    A[用户请求] --> B{路由匹配}
    B -->|命中静态文件| C[返回预渲染 HTML]
    B -->|动态路由| D[Swup 客户端平滑切页]
    C --> E[结束]
    D --> E
```

渲染效果：

flowchart TD
    A[用户请求] --> B{路由匹配}
    B -->|命中静态文件| C[返回预渲染 HTML]
    B -->|动态路由| D[Swup 客户端平滑切页]
    C --> E[结束]
    D --> E

flowchart TD 表示自上而下布局，改写成 LR 即为从左到右。

时序图（Sequence Diagram）

```mermaid
sequenceDiagram
    autonumber
    actor User as 访客
    participant Browser as 浏览器
    participant Server as 边缘服务器

    User->>Browser: 点击文章链接
    Browser->>Server: 发起页面资源请求
    Server-->>Browser: 返回纯静态 HTML 与资源包
    Browser-->>User: 渲染文章与动态配色
```

渲染效果：

sequenceDiagram
    autonumber
    actor User as 访客
    participant Browser as 浏览器
    participant Server as 边缘服务器

    User->>Browser: 点击文章链接
    Browser->>Server: 发起页面资源请求
    Server-->>Browser: 返回纯静态 HTML 与资源包
    Browser-->>User: 渲染文章与动态配色

autonumber 会自动为每条消息编号，实线箭头 ->> 表示请求，虚线箭头 -->> 表示响应。

状态图与架构图（State Diagram）

```mermaid
stateDiagram-v2
    [*] --> 默认浅色
    默认浅色 --> 暗色模式: 切换主题
    暗色模式 --> 默认浅色: 切换主题
    暗色模式 --> [*]
```

渲染效果：

stateDiagram-v2
    [*] --> 默认浅色
    默认浅色 --> 暗色模式: 切换主题
    暗色模式 --> 默认浅色: 切换主题
    暗色模式 --> [*]

甘特图（Gantt）

```mermaid
gantt
    title 内容上线节奏
    dateFormat  YYYY-MM-DD
    section 写作
    初稿            :a1, 2026-10-01, 3d
    配图与排版       :a2, after a1, 2d
    section 发布
    本地预览校对      :b1, after a2, 1d
    推送并构建        :b2, after b1, 1d
```

渲染效果：

gantt
    title 内容上线节奏
    dateFormat  YYYY-MM-DD
    section 写作
    初稿            :a1, 2026-10-01, 3d
    配图与排版       :a2, after a1, 2d
    section 发布
    本地预览校对      :b1, after a2, 1d
    推送并构建        :b2, after b1, 1d

核心特性

按需加载：Mermaid 引擎仅在文章包含图表代码块时才会动态异步加载，不增加其他页面的初始打包体积。
色彩与主题同步：图表线条、节点与文字颜色自动与当前站点的 Material 3 Expressive 主题色与明暗模式实时同步。

::: tip 图表代码也是代码 mermaid 代码块同样享有语法高亮、复制按钮与折叠能力，因此画错的图表可以直接从文章里复制出去调试。 :::

图表类型	代码首行	典型用途
流程图	`flowchart TD`	业务流程、渲染管线
时序图	`sequenceDiagram`	请求响应、协作过程
状态图	`stateDiagram-v2`	状态机、主题切换
甘特图	`gantt`	排期与时间线

代码选项组

Sat, 10 Oct 2026 00:00:00 GMT

代码选项组（Tabs）用于在同一区域并排切换展示不同包管理器命令（pnpm / npm / yarn / bun）、多种编程语言实现或不同操作系统的配置步骤。

语法格式

使用 ::: tabs 容器与 @tab 分割子标签页：

::: tabs#codeblock-package-managers

@tab pnpm#pnpm

```bash
pnpm install
pnpm build
```

@tab npm#npm

```bash
npm install
npm run build
```

@tab Bun#bun

```bash
bun install
bun run build
```

:::

渲染效果：

::: tabs#codeblock-package-managers

@tab pnpm#pnpm

pnpm install
pnpm build

@tab npm#npm

npm install
npm run build

@tab Bun#bun

bun install
bun run build

:::

多语言实现对比

同一段逻辑用不同语言书写时，选项组比「贴三段代码 + 小标题」更省版面：

::: tabs#fetch-json

@tab TypeScript#ts

```ts
const res = await fetch('/api/posts.json');
const posts = await res.json();
```

@tab Python#python

```python
import json, urllib.request
res = urllib.request.urlopen('/api/posts.json')
posts = json.load(res)
```

@tab Rust#rust

```rust
let res = reqwest::get("/api/posts.json").await?;
let posts: Vec<Post> = res.json().await?;
```

:::

渲染效果：

::: tabs#fetch-json

@tab TypeScript#ts

const res = await fetch('/api/posts.json');
const posts = await res.json();

@tab Python#python

import json, urllib.request
res = urllib.request.urlopen('/api/posts.json')
posts = json.load(res)

@tab Rust#rust

let res = reqwest::get("/api/posts.json").await?;
let posts: Vec<Post> = res.json().await?;

:::

指定默认激活项

::: tabs#shell-choice

@tab Bash#bash

```bash
pnpm content:sync
pnpm dev
```

@tab:active PowerShell#powershell

```powershell
$env:CONTENT_DIR = "<内容仓库的本地路径>"
pnpm content:sync
pnpm dev
```

:::

渲染效果：

::: tabs#shell-choice

@tab Bash#bash

pnpm content:sync
pnpm dev

@tab:active PowerShell#powershell

$env:CONTENT_DIR = "<内容仓库的本地路径>"
pnpm content:sync
pnpm dev

:::

默认激活与跨块联动

指定激活项：使用 @tab:active 显式设置默认选中的标签页。
全局同步联动：在同一页面中，拥有相同 #id 的选项卡（例如全站的 #pnpm 与 #npm）在用户点击一次后会自动全局联动切换。
无障碍支持：完全支持左右方向键键盘导航切换标签页。

::: tip 与 Markdown 选项卡的分工选项组容器既可用于代码，也可用于普通文本与表格，写法与代码选项组（Markdown 篇）完全一致，区别只在于内容组织方式。 :::

内容类型	推荐标识
包管理器命令	`#pnpm` / `#npm` / `#yarn` / `#bun`
语言实现	`#ts` / `#python` / `#rust`
部署平台	`#vercel` / `#cloudflare` / `#netlify`
操作系统	`#windows` / `#macos` / `#linux`

Shirone 双语文章指南

Fri, 09 Oct 2026 00:00:00 GMT

Shirone 的文章可以有多种内容语言版本。各语言版本并排放在同一个目录、共用一个 slug 并自动互相链接；顶栏与页面文案跟随当前 URL 的语言，聚合列表（归档、分类、标签）则始终只渲染默认语言。你正在阅读的这一页（以及它的英文孪生页）就是可运行的演示。

1. 文件布局

把每个语言版本放进同一个文章目录，每种语言一个文件，命名为 index.<locale>.md：

src/content/posts/bilingual-posts/
├── index.en.md        ← 默认语言（英语）
└── index.zh-CN.md     ← 简体中文

语言由文件名后缀派生，不需要额外的 frontmatter 字段：

index.en.md → 集合 id bilingual-posts
index.zh-CN.md → 集合 id zh-CN/bilingual-posts

默认语言文件也可以沿用不带后缀的 index.md——没有后缀即默认语言。两个文件之间的 published、tags、category 等结构性字段应保持一致，而 title / description 各自使用本语言撰写。

2. URL 映射

每种语言版本有独立路由。非默认语言的前缀取代 posts/ 段，而不是叠加：

	默认语言（en）	zh-CN
集合 id	`bilingual-posts`	`zh-CN/bilingual-posts`
路由	`/posts/bilingual-posts/`	`/zh/bilingual-posts/`
自定义 `permalink`	`/my-slug/`	`/zh/my-slug/`

:::tip 前缀由主题唯一的 [locale] 路由拥有，它按 contentI18n.locales （src/config/contentI18nConfig.ts）逐语言产出页面——增删语言只需改这张表。请求规范化（大小写变体、多余的默认语言前缀）由主题中间件处理——上面每一条映射的唯一真源都是 src/utils/i18n-routing.ts。 :::

3. 版本之间的互链

只要文章存在至少一个其它语言版本，正文前就会渲染**「本文还提供」**区块（位于封面与元信息之后）。它把每种其它语言列成一个带 hreflang 标注的链接胶囊——当前语言永远不会列出自己；单语文章则完全不渲染该区块，页面与未启用 i18n 的站点逐字节一致。

4. 顶栏语言菜单

搜索与调色板之间的翻译按钮，下拉展示同一套语言集合：

在文章页上，菜单列出本篇文章的所有语言版本，点击即切换；
首页在每种配置语言下都有对版（/ ↔ /zh/，点击即整页切换）；归档、订阅源等尚无对应语言版本的页面，缺失语言的条目呈禁用态。

菜单标签使用语言自称（endonym）——“English”、“简体中文”——不随站点界面语言翻译。

5. 跟随页面语言与保持默认语言的部分

界面文案跟随当前页面语言：/zh/* 下的顶栏、侧栏、分页与搜索面板都输出中文——本页即演示。跨语言的站内跳转走整页加载（Swup 的 ignoreVisit 守卫），持久外壳不会停留在旧语言上。

聚合内容则被刻意限定在默认语言：

归档、分类、标签、RSS/Atom 订阅源、llms.txt 与统计页始终只列出默认语言文章；中文首页（/zh/）只列出中文文章；
页面级元数据跟随文章语言：<html lang>、JSON-LD inLanguage、 og:url 与 Content-Language 都与你正在阅读的语言一致。

现在就试试顶栏的翻译按钮，或打开上方的互链区块——本文的英文版只有一次点击之遥。

代码折叠与复制

Fri, 09 Oct 2026 00:00:00 GMT

为了避免冗长的样板代码或超长配置文件占据过多版面，Shirone 提供了代码折叠行指令与一键复制功能。

代码折叠（collapse）

在元数据中使用 collapse={起始行-结束行} 指定默认折叠的代码范围：

```typescript collapse={4-8} title="长配置文件示例"
import { defineUserConfig } from 'astro/config';

export default defineUserConfig({
  // 折叠部分开始
  site: 'https://shirone.mysqil.com',
  base: '/',
  trailingSlash: 'always',
  output: 'static',
  // 折叠部分结束
  integrations: [],
});
```

渲染效果：

import { defineUserConfig } from 'astro/config';

export default defineUserConfig({
  // 折叠部分开始
  site: 'https://shirone.mysqil.com',
  base: '/',
  trailingSlash: 'always',
  output: 'static',
  // 折叠部分结束
  integrations: [],
});

被折叠的行在初次加载时显示为「展开 N 行」的交互按钮，读者点击后平滑展开完整内容。

多个折叠区间

collapse 支持同时传入多段范围，把不重要的区块分别收起：

```yaml collapse={1-3,9-11} title="config/site.yaml"
# 折叠区间一：顶部注释
# 只写想改的键，其余保持主题默认值
# 升级主题后新默认值会自动生效

site: https://www.example.com/
title: 我的博客
subtitle: 一个神奇的博客
lang: zh_CN

# 折叠区间二：页脚
# 这里放备案信息与统计代码
# 可以保持折叠状态
```

渲染效果：

# 折叠区间一：顶部注释
# 只写想改的键，其余保持主题默认值
# 升级主题后新默认值会自动生效

site: https://www.example.com/
title: 我的博客
subtitle: 一个神奇的博客
lang: zh_CN

# 折叠区间二：页脚
# 这里放备案信息与统计代码
# 可以保持折叠状态

一键复制代码

所有渲染的代码块在右上角均内置了优雅的一键复制按钮：

点击后自动将代码原始内容写入系统剪贴板。
复制成功后呈现微动效提示。
保证复制出的文本是纯净代码，绝不包含行号或标记字符。

即使在折叠状态下，复制按钮给出的仍然是完整的原始代码，而不是屏幕上可见的部分。

折叠与其它特性的组合

需求	写法
折叠中间区块	`collapse={4-8}`
折叠多段	`collapse={1-3,9-11}`
折叠 + 行号	`collapse={4-8} showLineNumbers`
折叠 + 文件名	`collapse={4-8} title="config/site.yaml"`

::: tip 折叠的边界折叠不是「隐藏信息」的手段。把全部关键代码都折起来会让读者跳过内容；建议只折叠样板引用、自动生成的默认值与重复的注释区块。 :::

高亮与差异标记

Thu, 08 Oct 2026 00:00:00 GMT

Shirone 支持对代码块中的特定行进行行高亮、新增行（insert）与删除行（delete）的视觉差异标记。

行高亮（行号范围）

在代码围栏首行通过 {1,3-5} 指定需要高亮的行号：

```typescript {2,4-5} title="src/index.ts"
function setup() {
  const isEnabled = true; // 第 2 行高亮
  const count = 0;
  console.log("初始化完成"); // 第 4-5 行高亮
  return count;
}
```

渲染效果：

function setup() {
  const isEnabled = true; // 第 2 行高亮
  const count = 0;
  console.log("初始化完成"); // 第 4-5 行高亮
  return count;
}

行号表达式支持逗号分隔的离散行（{2,7}）与连字符区间（{4-8}），两者可以混写。

差异标记（ins / del）

使用 ins={...} 标记新增行（绿色背景），del={...} 标记删除行（红色背景）：

```typescript ins={3} del={2} title="更新配置"
export const siteConfig = {
  themeColor: 210, // 旧配置
  themeColor: 315, // 新配置
};
```

渲染效果：

export const siteConfig = {
  themeColor: 210, // 旧配置
  themeColor: 315, // 新配置
};

两个属性也可以同时传入多行，并与行高亮叠加使用：

```ts ins={4-5} del={1} {4} title="src/site.ts"
const themeColor = 210;
export const siteConfig = {
  base: '/',
  themeColor: 315,
  trailingSlash: 'always',
};
```

渲染效果：

const themeColor = 210;
export const siteConfig = {
  base: '/',
  themeColor: 315,
  trailingSlash: 'always',
};

原生 Diff 代码块

也可以直接使用 diff 语言标识并以 + 和 - 作为行首字符：

```diff title="git diff"
- const oldVersion = "1.0.0";
+ const newVersion = "2.0.0";
```

渲染效果：

- const oldVersion = "1.0.0";
+ const newVersion = "2.0.0";

Diff 代码块完整保留标准 diff 语义，@@ 段落头、上下文行与 +/- 行都会被正确着色。

标记方式对照

写法	视觉结果	适用场景
`{2,4-5}`	中性行高亮背景	强调阅读重点
`ins={3}`	新增行配色	展示新增代码
`del={2}`	删除行配色	展示被移除的代码
```diff	完整 diff 着色	展示 `git diff` 原始输出

::: tip 什么时候用行高亮行高亮最适合「这份代码只改了一行」的场景。如果改动的行数超过整块代码的一半，高亮反而失去了指向性，此时直接贴出改动后的完整代码更清晰。 :::

标题与文件名

Wed, 07 Oct 2026 00:00:00 GMT

通过在代码块元数据中添加 title="..." 属性，可以为代码块生成带有文件类型图标的窗口顶栏与文件名标识。

语法格式

在代码围栏首行指定 title：

```json title="package.json"
{
  "name": "shirone",
  "version": "1.0.0"
}
```

渲染效果：

{
  "name": "shirone",
  "version": "1.0.0"
}

顶栏左端会根据扩展名渲染对应的文件类型图标，.json、.ts、.md、.astro 各有不同标识。

用标题描述操作步骤

标题不必是文件名，也可以是一句操作说明：

```bash title="终端操作命令"
pnpm install
pnpm dev
```

渲染效果：

pnpm install
pnpm dev

在文章中的实际用法

一次完整的配置说明通常会连续出现多个带文件名的代码块，读者据此就能判断每个片段应该写到哪个文件里：

先在站点配置中填写域名：

```yaml title="config/site.yaml"
site: https://www.example.com/
title: 我的博客
```

再在导航栏配置中加入菜单项：

```yaml title="config/nav-bar.yaml"
items:
  - name: 首页
    url: /
    icon: material-symbols:home-rounded
```

最后执行构建：

```bash title="本地预览"
pnpm content:sync
pnpm dev
```

渲染效果：

site: https://www.example.com/
title: 我的博客

items:
  - name: 首页
    url: /
    icon: material-symbols:home-rounded

pnpm content:sync
pnpm dev

视觉与特性

顶栏左侧自动渲染操作系统风格的窗口控制按钮与文件扩展名专用图标。
顶栏右侧自动放置快速复制代码按钮与折叠控制入口。
文件名标签清晰明确，避免读者混淆代码存放路径。

::: tip 命名规范文件路径建议与仓库中的真实路径保持一致（如 content/posts/hello/index.md 而不是 文章.md）。当读者照着代码块去仓库里找文件时，一致的路径能省掉大量猜测。 :::

元数据写法	顶栏显示	适用场景
`title="package.json"`	文件图标 + 文件名	真实存在的文件
`title="终端操作命令"`	纯文本标题	命令与临时片段
不写 `title`	仅显示复制按钮	无需标注来源的短片段

语法高亮与行号

Tue, 06 Oct 2026 00:00:00 GMT

Shirone 深度集成了 Expressive Code 引擎，提供基于 Shiki 的专业级静态语法着色与行号管理。

基础语法高亮

在代码块三个反引号后指定编程语言标识符：

```typescript
interface UserProfile {
  name: string;
  avatar: string;
  themeColor: number;
}
```

渲染效果：

interface UserProfile {
  name: string;
  avatar: string;
  themeColor: number;
}

语言标识符决定着色规则，常见取值包括 ts、js、astro、svelte、bash、yaml、json、markdown、diff。不写标识符时按纯文本渲染。

显示行号（showLineNumbers）

通过在元数据中添加 showLineNumbers 属性强制开启行号显示：

```rust showLineNumbers
fn main() {
    println!("Hello, Shirone!");
}
```

渲染效果：

fn main() {
    println!("Hello, Shirone!");
}

行号标记在服务端生成，复制代码时不会把行号带进剪贴板。

与其它元数据组合

代码围栏首行的元数据可以叠加书写，顺序不影响结果：

```typescript title="src/config.ts" showLineNumbers {2,5} collapse={7-9}
export const config = {
  themeColor: 315,
  analytics: false,
  comments: true,
  trailingSlash: 'always',

  // 以下是自动生成的默认区块
  base: '/',
  output: 'static',
  prefetch: true,
};
```

渲染效果：

export const config = {
  themeColor: 315,
  analytics: false,
  comments: true,
  trailingSlash: 'always',

  // 以下是自动生成的默认区块
  base: '/',
  output: 'static',
  prefetch: true,
};

元数据	作用	详见
`title="..."`	代码块顶栏文件名	标题与文件名
`showLineNumbers`	显示行号	本文
`{2,5}`	高亮指定行	高亮与差异标记
`collapse={7-9}`	折叠行范围	代码折叠与复制

特性与优势

零客户端运行时：所有语法高亮与行号标记在服务端完成静态预渲染，不会发生客户端样式闪烁。
自适应明暗配色：代码块根据当前站点的 M3E 配色调色板与暗色模式自动调整语法前景色与背景对比度。

::: tip 语言标识符写错会怎样未知的语言标识符不会导致构建失败，只是退化为无着色的纯文本。若发现代码块颜色异常，先检查标识符拼写。 :::

文件片段导入

Mon, 05 Oct 2026 00:00:00 GMT

文件片段导入语法允许在当前 Markdown 文章中引入其他文件的完整内容、行号切片或命名区块，极大提升长篇教程与公共配置文档的复用效率。

引入完整文件

在文章中使用注释指令：

<!-- @include: ../../snippets/include-example.md -->

路径相对于当前文章的 index.md 所在目录书写。本站的示例片段位于 content/snippets/include-example.md，因此从 posts/markdown-include/ 出发需要向上两级。

渲染效果：

按行号切片引入

只引入目标文件中指定范围的行：

<!-- @include: ../../snippets/include-example.md{5-9} -->

渲染效果：

行号从文件第一行开始计数（含首尾）。需要注意的是：行号会随片段文件被编辑而漂移，共享片段更推荐使用下面的命名区块方式。

按命名区块（Region）引入

在源码中使用 #region 和 #endregion 标记公共区块：

// #region auth-config
export const authConfig = {
  enabled: true,
  provider: 'github',
};
// #endregion

在 Markdown 中精准导入该区块：

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

渲染效果：

目标片段中的 #region public-api 与 #endregion public-api 之间的内容被精确提取，区块外的一行说明文字不会出现。

三种方式对照

方式	语法	稳定性
完整文件	`@include: path.md`	高，内容整体同步
行号切片	`@include: path.md{10-25}`	低，插入或删除行会导致偏移
命名区块	`@include: path.md#region-name`	高，按标记提取，位置自由

典型用法

公共前置条件：把「环境依赖」段落放进 snippets/prerequisites.md，所有教程文章统一导入。
配置片段：真实源码文件里标记 #region，文档直接引用，保证文档与代码永不脱节。
多语言文章：中英文文章共享同一段代码示例，避免两处维护。

构建特性

所有的片段嵌入均在构建编译期完成，输出标准的静态 AST 节点。
零运行时开销，代码高亮与行号完全同步生效。

::: warning 路径必须真实存在 @include 指向的文件在构建期被读取，路径写错会导致构建失败。片段文件建议统一放在 content/snippets/ 目录中，并用相对路径引用。 :::

图片画廊与排版

Sun, 04 Oct 2026 00:00:00 GMT

Shirone 提供了强大的多列图片画廊网格与单图尺寸排版控制能力，支持 Lightbox 放大预览与 WebP 自动压缩。

图片网格画廊（grid）

使用 ::: grid 容器将多张图片自动编排为响应式多列画廊：

::: grid{columns="3" aspect="16/9" fit="cover"}
![春日摄影](./spring.webp "樱花盛开")
![夏日海滩](./summer.webp "晴空与浪花")
![秋日落叶](./autumn.webp "枫叶大道")
:::

渲染效果：

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

点击任意一张图片即可进入 Lightbox 放大预览。

属性参数

columns：列数，支持 2、3、4（移动端自动响应退化为单列或双列）。
aspect：固定比例，如 16/9、4/3、1/1。
fit：图片适应方式，cover（填充裁剪）或 contain（完整包含）。

两列 + 完整包含的效果：

::: grid{columns="2" aspect="4/3" fit="contain"}
![春日摄影](./spring.webp "樱花盛开")
![夏日海滩](./summer.webp "晴空与浪花")
:::

::: grid{columns="2" aspect="4/3" fit="contain"} :::

cover 会裁掉超出比例的部分以保持整齐，contain 则完整保留画面但可能在容器内留白。风景照适合 cover，截图与图表适合 contain。

单图尺寸与标题控制

在普通 Markdown 图片语法的 alt 文本中直接标注宽度：

![架构图 w-60%](./spring.webp "系统数据流转架构图")

![图标 w-120px](./summer.webp "高清徽标")

渲染效果：

w-60%：将图片宽度限制为父容器的 60% 并水平居中。
引号中的内容自动渲染为图片下方的图题说明。

像素宽度效果：

参数对照

写法	作用	适用场景
`w-60%`	按父容器百分比缩放	正文中的大图
`w-240px`	固定像素宽度	图标、徽标、小截图
`::: grid{columns="3"}`	三列网格	同主题组图
`::: grid{aspect="1/1" fit="cover"}`	方形裁切	头像墙、封面墙

::: tip 图片存放建议把配图与 index.md 放在同一个文章文件夹中，用 ./file.webp 这类相对路径引用。这样文章迁移或归档时资源会一起被带走，也不会因为图床失效而产生死图。 :::

代码选项组

Sat, 03 Oct 2026 00:00:00 GMT

代码选项组（Tabs / Code Group）用于在同一卡片中并排切换展示多种编程语言、包管理器命令或不同环境的操作指南。

语法格式

使用 ::: tabs 容器与 @tab 分割子选项卡：

::: tabs#markdown-tabs-demo

@tab pnpm#pnpm

```bash
pnpm install
pnpm dev
```

@tab npm#npm

```bash
npm install
npm run dev
```

@tab Bun#bun

```bash
bun install
bun dev
```

:::

渲染效果：

::: tabs#markdown-tabs-demo

@tab pnpm#pnpm

pnpm install
pnpm dev

@tab npm#npm

npm install
npm run dev

@tab Bun#bun

bun install
bun dev

:::

@tab 标签文字#同步标识 是完整写法：井号前是显示文案，井号后是全站同步用的标识。

标签内容不限于代码

每个 @tab 内部都是完整的 Markdown 上下文，表格、列表、提示容器都可以放入：

::: tabs#deploy-target

@tab Vercel#vercel

在 Vercel 中导入内容仓库，构建命令填写 `pnpm build`。

| 配置项 | 值 |
| --- | --- |
| 输出目录 | `dist` |
| Node 版本 | 22 |

@tab Cloudflare Pages#cloudflare

在 Cloudflare Pages 中连接同一仓库。

| 配置项 | 值 |
| --- | --- |
| 构建命令 | `pnpm build` |
| 输出目录 | `dist` |

:::

渲染效果：

::: tabs#deploy-target

@tab Vercel#vercel

在 Vercel 中导入内容仓库，构建命令填写 pnpm build。

配置项	值
输出目录	`dist`
Node 版本	22

@tab Cloudflare Pages#cloudflare

在 Cloudflare Pages 中连接同一仓库。

配置项	值
构建命令	`pnpm build`
输出目录	`dist`

:::

指定默认激活项

使用 @tab:active 显式标记初次加载时选中的选项卡：

::: tabs#runtime-choice

@tab Node.js#node

Node.js 运行时。

@tab:active Bun#bun

Bun 运行时（默认选中）。

:::

渲染效果：

::: tabs#runtime-choice

@tab Node.js#node

Node.js 运行时。

@tab:active Bun#bun

Bun 运行时（默认选中）。

:::

核心特性

默认激活：使用 @tab:active 显式标记初次加载默认选中的选项卡。
全局同步：全站相同 #id 的选项卡（如 #pnpm）点击切换时会自动保持联动同步。
键盘导航：完全支持左右方向键切换焦点。

::: tip 全局同步的用法同一篇文章里放两组 #package-managers 选项卡，读者只要在其中一组里选择了 pnpm，另一组也会同步切到 pnpm。这在「安装依赖」与「执行构建」分成两个代码块时尤其顺手。 :::

需求	推荐写法
切换命令或代码	`::: tabs` + `@tab`
折叠而不切换	代码折叠 `collapse={4-8}`
强调差异	差异标记 `ins` / `del`

代码树

Fri, 02 Oct 2026 00:00:00 GMT

代码树是一个将「左侧文件树导航」与「右侧代码高亮展示」无缝结合的高级复合组件，非常适合展示多文件工程示例与组件封装结构。

容器语法

在 code-tree 容器内包裹多个带有 title 属性的代码块：

::: code-tree{title="按钮组件封装" entry="Button.svelte" height="380px"}

```svelte title="Button.svelte"
<script lang="ts">
  export let variant: 'primary' | 'secondary' = 'primary';
</script>

<button class="btn btn-{variant}">
  <slot />
</button>
```

```ts title="types.ts"
export type ButtonVariant = 'primary' | 'secondary';
```

:::

渲染效果：

::: code-tree{title="按钮组件封装" entry="Button.svelte" height="380px"}

<script lang="ts">
  export let variant: 'primary' | 'secondary' = 'primary';
</script>

<button class="btn btn-{variant}">
  <slot />
</button>

export type ButtonVariant = 'primary' | 'secondary';

:::

每个代码块的 title 就是它在左侧树中的文件名，entry 指定首次加载时默认激活的文件，height 控制整体高度。

用嵌套路径表达多层目录

代码块的 title 支持用 / 书写层级，左侧会自动生成对应的目录树：

::: code-tree{title="配置叠加示例" entry="user-config.ts" height="420px"}

```ts title="src/user/user-config.ts"
import site from '../../config/site.yaml';
export default { site };
```

```yaml title="config/site.yaml"
site: https://example.com/
title: 我的博客
```

```ts title="src/config/siteConfig.ts"
export const siteConfig = {
  base: '/',
  trailingSlash: 'always',
};
```

:::

渲染效果：

::: code-tree{title="配置叠加示例" entry="src/user/user-config.ts" height="420px"}

import site from '../../config/site.yaml';
export default { site };

site: https://example.com/
title: 我的博客

export const siteConfig = {
  base: '/',
  trailingSlash: 'always',
};

:::

本地目录直接导入语法

Shirone 支持直接通过文件路径导入本地工程目录生成代码树：

@[code-tree title="站点基础配置" entry="siteConfig.ts"](/src/config)

渲染效果：

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

::: warning 路径基准 @[code-tree] 的路径以仓库根目录为基准，构建期会读取该目录下的真实文件。若目录不存在或为空，会回退为空的导航面板。发布到博客时，路径必须指向站点仓库中确实存在的目录。 :::

参数一览

参数	类型	是否必填	说明
`title`	`string`	可选	代码树顶栏标题
`entry`	`string`	可选	默认激活的文件名（或相对路径）
`height`	`string`	可选	容器高度，如 `380px`、`60vh`

交互特性

双栏联动：点击左侧树状结构中的任意文件名，右侧代码区即时切换至对应的文件内容与语法高亮。
默认入口：通过 entry="filename" 指定页面首次加载时默认激活展示的文件。
自适应滚动：高度与滚动条经过无障碍与移动端优化，保持阅读舒适。

文件树

Thu, 01 Oct 2026 00:00:00 GMT

文件树组件用于展示项目的目录与文件结构，支持自动识别文件扩展名图标、目录层级折叠以及变更状态标注。

语法格式

支持容器语法与代码围栏双语法。

容器语法

::: file-tree{title="Shirone 目录结构"}
- src/
  - config/
    - siteConfig.ts
    - sidebarConfig.ts
  - content/
    - posts/
      - hello-world.md
  - astro.config.mjs
- package.json
- pnpm-lock.yaml
:::

渲染效果：

::: file-tree{title="Shirone 目录结构"}

src/
- config/
  - siteConfig.ts
  - sidebarConfig.ts
- content/
  - posts/
    - hello-world.md
- astro.config.mjs
package.json
pnpm-lock.yaml :::

围栏代码块语法

```file-tree title="构建输出"
dist/
├── assets/
│   ├── app.js
│   └── style.css
├── index.html
└── pagefind/


**渲染效果**：

```file-tree title="构建输出"
dist/
├── assets/
│   ├── app.js
│   └── style.css
├── index.html
└── pagefind/

::: tip 两种语法怎么选容器语法用嵌套列表书写，随手增删层级不必手动对齐制表符连线；围栏语法更适合直接从 tree 命令粘贴输出。 :::

变更状态与图标智能匹配

在条目前添加符号即可标注差异状态：

::: file-tree{title="本次提交的改动"}
- src/
  - content/
    ~ posts/
      + markdown-file-tree/
      - legacy-notes.md
  ~ astro.config.mjs
  + src/utils/markdown-diff.ts
:::

渲染效果：

::: file-tree{title="本次提交的改动"}

src/
- content/ ~ posts/
  - markdown-file-tree/
  - legacy-notes.md ~ astro.config.mjs
- src/utils/markdown-diff.ts :::

符号	含义	视觉表达
`+`	新增	新增状态指示色
`-`	删除	删除状态指示色
`~`	修改	修改状态指示色

渲染特性

扩展名识别：自动根据文件后缀（如 .ts、.json、.astro、.md、.css、.png）匹配对应的 Material / Devicon 图标。
差异标记：支持在条目前添加 +（新增）、-（删除）、~（修改）等符号，自动生成带颜色的差异状态指示。
原生折叠：包含子目录的节点默认支持可折叠展开交互。

与代码树的区别

需求	推荐组件
只看目录结构	`file-tree`
目录 + 多文件源码并排查看	代码树

步骤引导

Wed, 30 Sep 2026 00:00:00 GMT

步骤引导容器 steps 用于编写安装指南、配置教程或操作流程，将原本扁平的有序数字列表渲染为带有连线与徽章的视觉流程图。

语法格式

使用 ::: steps 容器包裹标准 Markdown 有序列表：

::: steps{title="快速上手三步曲"}

1. **安装环境依赖**

   确保本地 Node.js 版本满足 `>= 22.12`，并安装 pnpm 包管理器。

2. **克隆并初始化仓库**

   ```bash
   git clone https://github.com/LyraVoid/Shirone.git
   cd Shirone
   pnpm install
   ```

3. **启动本地开发服务器**

   运行 `pnpm dev` 并在浏览器中访问 `http://localhost:4321`。

:::

渲染效果：

::: steps{title="快速上手三步曲"}

安装环境依赖

确保本地 Node.js 版本满足 >= 22.12，并安装 pnpm 包管理器。

克隆并初始化仓库

git clone https://github.com/LyraVoid/Shirone.git
cd Shirone
pnpm install

启动本地开发服务器

运行 pnpm dev 并在浏览器中访问 http://localhost:4321。

:::

方括号标题形式

标题也支持方括号写法，适合标题中包含标点的情况：

::: steps[发布前检查清单]
1. 运行 `pnpm.cmd astro check`，确认 0 错误
2. 运行 `pnpm.cmd build`，确认无警告
3. 推送内容仓库，等待跨仓构建
:::

渲染效果：

::: steps[发布前检查清单]

运行 pnpm.cmd astro check，确认 0 错误
运行 pnpm.cmd build，确认无警告
推送内容仓库，等待跨仓构建 :::

步骤内部可以放什么

每一步都是一个完整的 Markdown 上下文，可以自由嵌套段落、代码块、提示容器与图片：

::: steps{title="配置评论系统"}

1. **填写环境变量**

   ::: warning 注意
   变量名区分大小写。
   :::

2. **在配置文件中启用**

   ```yaml title="config/comment.yaml"
   enable: true
   provider: twikoo
   ```

:::

渲染效果：

::: steps{title="配置评论系统"}

填写环境变量

::: warning 注意变量名区分大小写。 :::
在配置文件中启用
```
enable: true
provider: twikoo
```

:::

与普通有序列表的区别

场景	推荐写法
有先后依赖的操作流程	`::: steps` 容器
并列的要点罗列	普通有序列表 `1. 2. 3.`
无需顺序的清单	无序列表 `-`

渲染特性

序号圆圈与竖向引导连线完全由 CSS 伪元素与 Material 3 令牌驱动，语义结构保持为标准的 <ol> 列表。
支持在每个步骤内部自由嵌套段落、代码块、提示容器或图片。

卡片与字段组

Tue, 29 Sep 2026 00:00:00 GMT

Shirone 提供了丰富的卡片系统，包括 GitHub 仓库卡片、API 字段参数卡片组以及折叠卡片组。

GitHub 仓库卡片

使用 ::github 指令自动拉取并展示 GitHub 仓库信息（含名称、简介、Star 数与主语言）：

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

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

渲染效果：

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

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

仓库信息在构建期获取并缓存，页面本身不会在浏览器里请求 GitHub API。

API 字段参数卡片组

在编写技术文档、API 说明或配置项手册时，使用 field-group 与 field 容器生成结构化的参数卡片：

:::: field-group

::: field title
@type string
@required

网站正式标题，显示在顶栏和浏览器标签页。
:::

::: field subtitle
@type string
@optional

网站副标题，用于元数据与首页辅助展示。
:::

::: field themeColor
@type number
@optional
@default 315

主题色相值，决定全站的动态配色基准。
:::

::::

渲染效果：

:::: field-group

::: field title @type string @required

网站正式标题，显示在顶栏和浏览器标签页。 :::

::: field subtitle @type string @optional

网站副标题，用于元数据与首页辅助展示。 :::

::: field themeColor @type number @optional @default 315

主题色相值，决定全站的动态配色基准。 :::

::::

字段名写在 ::: field 之后，首段以 @ 开头的行用于声明类型与约束：

标记	含义
`@type <类型>`	参数数据类型
`@required`	必填项
`@optional`	可选项
`@default <值>`	默认值

折叠面板卡片

::: collapse accordion
- :+ 默认展开的项目

  这里是第一个卡片的内容正文。

- 默认折叠的项目

  这里是第二个卡片的内容正文。
:::

渲染效果：

::: collapse accordion

:+ 默认展开的项目

这里是第一个卡片的内容正文。
默认折叠的项目

这里是第二个卡片的内容正文。 :::

:+ 前缀标记该项默认展开，未标注的项默认折叠。

::: tip 自包含的单卡不写 accordion 时，collapse 容器渲染为独立的折叠卡片： :::

::: collapse
- 独立的折叠标题

  折叠正文内容。
:::

渲染效果：

::: collapse

独立的折叠标题

折叠正文内容。 :::

选型对照

信息形态	推荐组件
一个开源仓库的概览	`::github` 卡片
一组配置项的逐条说明	`field-group`
需要读者主动展开的长内容	`collapse`

Github 警报

Mon, 28 Sep 2026 00:00:00 GMT

Shirone 原生支持 GitHub 官方的警报块语法，无需任何指令转换即可将 GitHub Markdown 样式的引用块渲染为现代化的警报容器。

语法格式

使用标准引用语法 > 开头，首行书写大写的警报类型标记：

> [!NOTE]
> 这是普通笔记说明，适合记录背景信息。

> [!TIP]
> 这是操作小技巧，帮助提升工作流效率。

> [!IMPORTANT]
> 核心关键配置，部署生产前请务必确认。

> [!WARNING]
> 潜在风险预警，请注意参数兼容性。

> [!CAUTION]
> 危险操作提醒，执行前请先做好数据备份。

渲染效果：

[!NOTE] 这是普通笔记说明，适合记录背景信息。

[!TIP] 这是操作小技巧，帮助提升工作流效率。

[!IMPORTANT] 核心关键配置，部署生产前请务必确认。

[!WARNING] 潜在风险预警，请注意参数兼容性。

[!CAUTION] 危险操作提醒，执行前请先做好数据备份。

多行内容与嵌套语法

警报块内部依旧是普通引用上下文，可以承载多段文字、列表与代码：

> [!TIP]
> 提交前建议依次执行：
>
> 1. `pnpm.cmd astro check`
> 2. `pnpm.cmd build`
>
> 两条命令都通过后，再推送内容仓库。

渲染效果：

[!TIP] 提交前建议依次执行：

pnpm.cmd astro check

pnpm.cmd build

两条命令都通过后，再推送内容仓库。

五种警报的适用边界

标记	语义强度	建议用途
`[!NOTE]`	中性	背景信息、补充说明
`[!TIP]`	中性偏轻	提效技巧、可选的优化手段
`[!IMPORTANT]`	高	必须知晓的前提条件
`[!WARNING]`	高	可能出错但可恢复的操作
`[!CAUTION]`	最高	不可逆或高成本的操作

与通用提示容器的互通性

内部统一转译为与提示容器相同的语义 AST 节点。
保证在 GitHub 仓库原生 README 预览与博客正文发布时拥有一致的排版呈现。

::: tip 该选哪一种写法在需要同时出现在 GitHub README 与博客里的文档中，使用 > [!NOTE] 形式；只在博客中发布的文章，用提示容器的 ::: tip 形式书写更自由，标题也支持自定义。 :::

> [!WARNING]
> GitHub 端只识别这五种固定标记，写成 `> [!DANGER]` 会被当作普通引用渲染。

提示容器

Sun, 27 Sep 2026 00:00:00 GMT

提示容器用于在文章中高亮特定级别的提示、警告、注意或可折叠区域，严格遵循 Material 3 Expressive 的容器表面分层设计。

语法格式

支持方括号标题与空格标题两种书写形式：

::: tip[操作提示]
建议在修改核心配置前先运行类型检查。
:::

::: warning 部署前检查
若未配置正式域名，社交分享卡片可能无法正确生成。
:::

两种写法完全等价，方括号形式更适合标题中包含空格或标点的场景。

渲染效果：

::: tip[操作提示] 建议在修改核心配置前先运行类型检查。 :::

::: warning 部署前检查若未配置正式域名，社交分享卡片可能无法正确生成。 :::

全部容器类型

::: info 相关参考
关于双仓架构的更多细节，请参阅内容分离指南。
:::

::: caution 破坏性操作
执行此命令将清除本地未提交的改动。
:::

::: important 关键结论
构建产物的体积直接决定首屏耗时。
:::

::: note 普通笔记
这一条只是补充记录，不构成操作建议。
:::

渲染效果：

::: info 相关参考关于双仓架构的更多细节，请参阅内容分离指南。 :::

::: caution 破坏性操作执行此命令将清除本地未提交的改动。 :::

::: important 关键结论构建产物的体积直接决定首屏耗时。 :::

::: note 普通笔记这一条只是补充记录，不构成操作建议。 :::

折叠面板 details

details 容器渲染为原生的 <details> 折叠组件，适合放置日志、长清单与可选的补充说明：

::: details 点击展开详细日志
构建过程的详细输出如下：

- 同步完成
- 生成静态 HTML 成功
:::

渲染效果：

::: details 点击展开详细日志构建过程的详细输出如下：

同步完成
生成静态 HTML 成功 :::

支持的容器类型一览

类型	语义	视觉风格
`tip`	技巧与建议	强调色彩容器与灯泡图标
`info`	补充信息	主色调表面与信息图标
`warning`	注意与预警	警示色调与三角感叹号
`caution`	危险操作	错误色调与高对比警示框
`important`	关键重点	鲜亮强调容器
`note`	普通笔记	中性表面容器
`details`	折叠面板	带箭头的原生 details 折叠组件

容器内部可以放什么

容器内部是完整的 Markdown 上下文，可以嵌套列表、代码块、表格乃至其它容器：

::: warning 依赖版本要求
本地 Node.js 版本必须满足 `>= 22.12`：

```bash
node -v
```
:::

渲染效果：

::: warning 依赖版本要求本地 Node.js 版本必须满足 >= 22.12：

node -v

:::

::: tip 与 GitHub 警报的关系 > [!NOTE] 这类 GitHub 警报会被统一转译为同一套容器节点，两种写法混用时视觉完全一致，详见Github 警报。 :::

内容注释

Sat, 26 Sep 2026 00:00:00 GMT

内容注释提供了比传统脚注更为生动、交互式的旁注说明系统，支持行内标记与右侧边缘卡片联动。

语法格式

在正文中使用 [+tag] 插入引用标记，并在下方或文末定义注释块：

Astro 采用孤岛架构 [+islands] 来保持页面的极速加载。

[+islands]:
  孤岛架构指由静态 HTML 所包裹的独立交互组件区域，只有交互区域才加载 JavaScript。

渲染效果：Astro 采用孤岛架构 [+islands] 来保持页面的极速加载。

[+islands]: 孤岛架构指由静态 HTML 所包裹的独立交互组件区域，只有交互区域才加载 JavaScript。

标记名 islands 只是一个标识符，正文中的 [+islands] 与定义块 [+islands]: 通过它配对，两者出现的先后顺序不作要求。

一篇多处注释

站点在构建期完成 SSR [+ssr]，产物是纯静态文件，因此首屏没有水合等待 [+hydration]。

[+ssr]:
  服务端渲染。页面 HTML 在构建阶段就已生成。

[+hydration]:
  水合。浏览器接管静态 HTML 并挂载交互逻辑的过程。

渲染效果：站点在构建期完成 SSR [+ssr]，产物是纯静态文件，因此首屏没有水合等待 [+hydration]。

[+ssr]: 服务端渲染。页面 HTML 在构建阶段就已生成。

[+hydration]: 水合。浏览器接管静态 HTML 并挂载交互逻辑的过程。

与脚注的取舍

对比项	内容注释 `[+tag]`	传统脚注 `[^1]`
展示位置	桌面端固定在右侧旁注区	文末统一罗列
阅读动线	无需跳转，视线水平移动即可	需要上下跳跃
移动端表现	轻触唤出居中浮层	跳转到文末锚点
适合内容	术语解释、补充说明、延伸阅读	引用出处、法律声明

渲染效果与交互

行内标记：正文中的标记呈现为精巧的高亮徽标。
桌面端旁注：在大屏幕设备上，注释内容优雅地显示在右侧边栏旁注区域。
移动端弹出：在触屏或窄屏设备上，轻触标记即可唤出居中浮层卡片查看详细注释。
纯静态输出：注释内容直接由服务端输出，兼顾无障碍访问与爬虫抓取。

::: tip 内容长度单条注释建议控制在两到三行以内。更长的补充材料更适合写成 ::: details 折叠块，或直接并入正文。上方的 [+islands] 与 [+hydration] 就是合理长度的示例。 :::

缩写词悬浮

Fri, 25 Sep 2026 00:00:00 GMT

缩写词语法用于在文章中对专业术语进行统一定义，并在正文中自动渲染为带有原生气泡提示的 <abbr> 元素。

语法格式

在文章任意位置（通常在文末或章节开头）声明缩写词字典：

*[SSR]: 服务端渲染技术
*[LCP]: 最大内容绘制时间指标
*[AST]: 抽象语法树

随后在正文直接书写该缩写词：

采用 SSR 可以大幅优化站点的 LCP 表现，并在 AST 解析阶段完成静态转换。

渲染效果：采用 SSR 可以大幅优化站点的 LCP 表现，并在 AST 解析阶段完成静态转换。

把鼠标悬停在 SSR、LCP 或 AST 上即可看到对应的中文解释。

*[SSR]: 服务端渲染技术 *[LCP]: 最大内容绘制时间指标 *[AST]: 抽象语法树

自动匹配规则

字典声明之后，同一篇文章中所有匹配到的词条都会被转换为缩写词，无需逐处手动标注：

SSR 的输出是纯 HTML，因此 SSR 页面在网络条件较差时依然可以快速呈现首屏。

渲染效果：SSR 的输出是纯 HTML，因此 SSR 页面在网络条件较差时依然可以快速呈现首屏。

匹配以词为单位进行，SSR 不会影响 SSRConfig 这样的长词。大小写敏感，ssr 不会被替换。

渲染机制

自动匹配：同一文章中所有匹配到的词条都会自动转换为带有语义下划线的缩写词。
现代化气泡定位：采用原生 Popover 顶层与 CSS Anchor 定位技术，悬浮窗不会被侧栏或父容器边界遮挡裁剪，无需等待浏览器默认的 title 延迟。
按需加载：只有在检测到缩写词语法的文章中才会激活轻量交互模块。

::: tip 写作建议缩写词字典适合定义首次出现的行业内术语。如果一篇文章需要解释十几个缩写，说明这些术语本身值得单独写一篇术语表，而不是塞进同一篇正文。 :::

写法	适用场景
`*[SSR]: 服务端渲染`	通用术语，全文自动生效
`SSR（服务端渲染）`	只解释一次，不希望后续都被标记
`<abbr title="...">`	需要精确控制单处标记

隐秘文本

Thu, 24 Sep 2026 00:00:00 GMT

隐秘文本（黑幕防剧透）用于遮盖关键剧情、谜题答案或敏感信息，读者在鼠标悬停或触屏轻触后方可显现内容。

语法格式

使用 :spoiler 指令包裹隐藏内容：

这个故事最后的结局是 :spoiler[真相其实是两个人早已相识]。

最终通关的正确密码为 :spoiler[42-7890]。

渲染效果：这个故事最后的结局是 :spoiler[真相其实是两个人早已相识]。

渲染效果：最终通关的正确密码为 :spoiler[42-7890]。

在段落与列表中使用

指令属于行内语法，可以嵌在任意文本流里：

- 第一位登场的角色是 :spoiler[戴着红围巾的少年]
- 关键道具藏在 :spoiler[钟楼顶层的暗格里]
- 隐藏结局的触发条件是 :spoiler[在第三章前收集齐三枚徽章]

渲染效果：

第一位登场的角色是 :spoiler[戴着红围巾的少年]
关键道具藏在 :spoiler[钟楼顶层的暗格里]
隐藏结局的触发条件是 :spoiler[在第三章前收集齐三枚徽章]

表格单元格中也能使用：

谜题	答案
房间的密码是多少？	:spoiler[带星号的那串数字]
谁是真正的委托人？	:spoiler[一直沉默的那位管家]

交互与特性

默认状态下呈现不透明的防剧透遮罩背景。
鼠标悬停（桌面端）或点击（移动触屏端）时柔和淡入真实文字。
使用纯 CSS 与轻量交互实现，兼顾移动设备兼容性与阅读隐私。

::: warning 它不是安全机制遮罩只防止「无意间扫到」，被遮盖的文字依然存在于页面源码中。密码、密钥、Token 之类的真正敏感信息请使用文章加密功能（encrypted: true + password），而不是隐秘文本。 :::

需求	推荐方案
防止读者无意中看到剧情	`:spoiler[...]`
放置趣味谜底、答案	`:spoiler[...]`
保护口令、密钥、隐私数据	文章加密

马克笔高亮

Wed, 23 Sep 2026 00:00:00 GMT

马克笔语法为正文中的短语提供醒目的荧光高亮视觉效果，基于原生语义化 <mark> 标签渲染。

基础语法

使用成对的双等号 == 包裹需要高亮的文字：

在撰写文章时，使用 ==主题主色高亮== 标记核心要点与结论。

渲染效果：在撰写文章时，使用 ==主题主色高亮== 标记核心要点与结论。

语义状态后缀

可以通过大括号后缀指定特定的语义色彩角色：

==次级强调状态=={.secondary}

==警告与需要修正的条件=={.error}

==建议与辅助提示=={.tip}

==三级调色板强调=={.tertiary}

渲染效果：

次级强调：==次级强调状态=={.secondary}
警告色彩：==警告与需要修正的条件=={.error}
辅助提示：==建议与辅助提示=={.tip}
三级强调：==三级调色板强调=={.tertiary}

后缀语法与扩展与属性共用同一套属性字典，因此多个 class 可以叠加：

==多重角色高亮=={.secondary .tip}

渲染效果：==多重角色高亮=={.secondary .tip}

与其它强调方式的对比

语法	输出标签	典型用途
`文本`	`<strong>`	语义上的重要内容
`文本`	`<em>`	语气强调、书名与术语
`文本`	`<code>`	代码标识符、字段名
`==文本==`	`<mark>`	视觉上的荧光标注

渲染效果：语义重要、语气强调、inline-code、==荧光标注==

::: tip 使用尺度马克笔是视觉工具而不是语义工具。同一屏内出现三处以上的高亮，读者就会失去视觉锚点；建议只在结论、易错点与关键参数上使用。 :::

渲染特性

生成标准的 <mark> HTML 标签，保障屏幕阅读器与辅助工具的可访问性。
高亮背景色完全由 Material 3 Expressive 的语义调色板驱动，与站点的主题色动态同步。
纯服务端渲染，无任何客户端脚本开销。

响应式表格

Tue, 22 Sep 2026 00:00:00 GMT

Shirone 增强了 GitHub Flavored Markdown 标准表格的排版与交互体验，在构建期通过专门的渲染插件自动生成响应式滚动包裹层。

标准表格语法

| 功能模块 | 对应状态 | 默认值 | 说明 |
| :--- | :---: | :---: | --- |
| 动态配色 | 稳定 | 315 | 默认粉紫色色相 |
| 无刷新切页 | 启用 | true | 基于 Swup 4 框架 |
| 零额外负担 | 严格遵循 | true | 页面关闭功能时零请求零体积 |

渲染效果：

功能模块	对应状态	默认值	说明
动态配色	稳定	315	默认粉紫色色相
无刷新切页	启用	true	基于 Swup 4 框架
零额外负担	严格遵循	true	页面关闭功能时零请求零体积

单元格内同样支持行内语法，例如 代码、加粗、链接与 ==高亮==：

属性名	类型	是否必填	默认值
`bvid`	`string`	必填	无
`title`	`string`	必填	无
`p`	`number`	可选	`1`
`preload`	`string`	可选	`"none"`

对齐方式

:---：左对齐
:---:：居中对齐
---:：右对齐

| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |
| 文本 | 文本 | 文本 |
| 较长的左对齐内容 | 状态徽标 | 1,024 |

渲染效果：

左对齐	居中	右对齐
文本	文本	文本
较长的左对齐内容	状态徽标	1,024

左侧冒号决定整列的对齐规则，不书写冒号时默认沿用左对齐。

移动端响应式支持

在窄屏或移动端设备上，当表格列数较多或内容超出屏幕宽度时：

构建期插件自动为表格注入外层响应式容器与平滑滚动样式。
绝不会发生撑破页面视口或导致水平全局溢出的情况。
表头固定与交替斑马纹背景完全遵循 Material 3 Expressive 的表面容器设计规范。

::: tip 写作建议表格最适合承载「参数、对照、状态」这类结构化信息。如果每个单元格都要写上一段说明，说明它更适合改成字段卡片组（见卡片与字段组）或普通列表。 :::

场景	推荐载体
参数与默认值对照	表格
单个配置项的详细解释	字段卡片组
操作顺序说明	步骤引导
需要折叠的长清单	折叠面板

数学公式

Mon, 21 Sep 2026 00:00:00 GMT

Shirone 集成了 KaTeX 数学排版引擎，支持行内公式与独立块级公式的高性能服务端静态渲染。

行内公式

使用单个美元符号 $ 包裹 TeX 公式：

质能守恒方程为 $E = mc^2$。

欧拉恒等式为 $e^{i\pi} + 1 = 0$。

渲染效果：

质能守恒方程为 $E = mc^2$。

欧拉恒等式为 $e^{i\pi} + 1 = 0$。

行内公式可以和普通文字、行内代码 与加粗文本自由混排，基线对齐由 KaTeX 自动处理。

块级公式

使用双美元符号 $$ 包裹独立公式块：

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

渲染效果：

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

矩阵与联立方程同样支持：

$$
\begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
\begin{pmatrix}
x \\
y
\end{pmatrix}
=
\begin{pmatrix}
ax + by \\
cx + dy
\end{pmatrix}
$$

渲染效果：

$$ \begin{pmatrix} a & b \ c & d \end{pmatrix} \begin{pmatrix} x \ y \end{pmatrix}

\begin{pmatrix} ax + by \ cx + dy \end{pmatrix} $$

分式、求和与极限等常见结构也可以一并书写：

$$ \sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}, \qquad \lim_{x \to 0} \frac{\sin x}{x} = 1 $$

优势与特性

SSR 静态生成：公式在构建阶段直接渲染为轻量 HTML 与 MathML 标记，无需在客户端动态加载庞大的 JavaScript 渲染引擎。
动态配色跟随：公式符号与背景色自动适配当前主题的 HCT 调色板与暗色模式。
可访问性与可复制性：输出包含 MathML 语义结构，屏幕阅读器可以朗读公式，复制出的文本也是原始 TeX。

::: tip 书写提示块级公式的 $$ 建议独占一行，并与上下段落之间保留空行；矩阵中换行使用 \\，列分隔使用 &。若公式中包含 $ 字面量，请用反斜线转义为 \$。 :::

语法	效果	说明
$...$	行内公式	跟随文字基线，适合符号与短表达式
`$$...$$`	块级公式	独立成行居中展示，适合推导过程
`\begin{pmatrix}...\end{pmatrix}`	矩阵	需要 `amsmath` 风格的 TeX 结构

原生表情与图标

Sun, 20 Sep 2026 00:00:00 GMT

Shirone 全面支持原生 Unicode Emoji 与现代化矢量图标库，兼具极高清晰度与零体积损耗。

原生 Unicode Emoji

Shirone 直接基于标准 UTF-8 编码渲染原生 Emoji，无需额外的转译插件或客户端字典。你可以把它们写进段落、标题、列表，甚至 frontmatter：

## 支持的平台 🎯

- 🚀 构建阶段完成静态提取
- 🎨 配色跟随主题动态变化
- 🧩 组件按需加载

渲染效果：

🚀 构建阶段完成静态提取
🎨 配色跟随主题动态变化
🧩 组件按需加载

标题中同样可以直接书写，例如「支持的平台 🎯」，它会被原样纳入右侧目录。

::: tip 使用建议 Emoji 属于系统字体渲染，不同操作系统与浏览器呈现的字形会有细微差别（Windows 与 macOS 的彩色字形风格并不相同）。装饰性使用完全没有问题，但不要用 Emoji 承载关键语义。 :::

矢量图标系统

Shirone 深度集成了 Iconify 与 Material Symbols 图标集：

在站点配置、导航栏、侧边栏卡片与自定义组件中，可直接使用标准图标标识符（如 ri:book-open-line、material-symbols:apps-rounded、fa6-brands:github）。
图标在构建期进行静态提取与 SVG 矢量内嵌，无需引入整套图标字体包。

以导航栏配置为例，图标标识符直接写在 YAML 中：

items:
  - name: 首页
    url: /
    icon: material-symbols:home-rounded
  - name: 归档
    url: /archive/
    icon: material-symbols:inventory-2-rounded
  - name: GitHub
    url: https://github.com/LyraVoid/Shirone
    icon: fa6-brands:github

侧边栏卡片同理，icon 字段接受任意 Iconify 标识符：

widgets:
  - type: profile
    icon: material-symbols:account-circle-rounded
  - type: announcement
    icon: ri:notification-3-line

::: warning 正文不解析图标标识符图标语法只在配置项与组件属性中生效。在 Markdown 正文里直接书写 material-symbols:home-rounded 不会渲染为图标——若需要在正文中插入矢量图形，请使用内嵌 SVG 或 <img> 标签。 :::

图标集合查找

你可以访问 icones.js.org 浏览和检索数万款可用图标的编码标识符，复制「Iconify 名称」即可直接填入配置。

图标集前缀	风格	适用场景
`material-symbols:`	Material 3 官方符号	与主题视觉最统一
`ri:`	Remix Icon 线性	轻量线性图标
`fa6-brands:`	Font Awesome 品牌	社交平台与品牌标识

图标在服务端完成 SVG 内联，页面加载后不会产生额外的图标请求，也不存在图标字体常见的首屏闪烁问题。

扩展与属性

Sat, 19 Sep 2026 00:00:00 GMT

Shirone 支持在 Markdown 元素后附加属性字典，为生成的 HTML 标签赋予自定义 class、id 或数据属性。它让「标准语法」与「自定义样式钩子」之间不再需要手写 HTML。

行内元素属性

在行内文本、链接或高亮语法后紧跟 {} 声明属性：

[外部链接](https://example.com){target="_blank" rel="noopener"}

==高亮文本=={.secondary}

`code phrase`{.custom-badge}

渲染效果：

新标签页打开：外部链接{target="_blank" rel="noopener"}
次级语义高亮：==高亮文本=={.secondary}
带自定义 class 的行内代码：code phrase{.custom-badge}

三项属性最终都会落到生成的 HTML 标签上：链接多出 target 与 rel，<mark> 多出 secondary class，<code> 多出 custom-badge class。前者立即可见（点击不会跳出站内浏览），后两者只有在你为这些 class 写了样式时才产生视觉差异。

块级元素属性

在块级容器、标题或段落后声明：

## 自定义锚点标题 {#custom-section-id}

::: tip[自定义样式容器]{class="custom-highlight-box"}
容器内部内容
:::

渲染效果：

自定义锚点标题 {#custom-section-id}

::: tip[自定义样式容器]{class="custom-highlight-box"} 容器内部内容 :::

上例中的标题被注入了 id="custom-section-id"，因此可以直接被 #custom-section-id 锚点定位；容器则同时保留 tip 的默认外观并额外挂上 custom-highlight-box class。

::: tip 关于自定义 class Shirone 只负责把属性写入标签，不会自动生成对应样式。想真正看到 custom-highlight-box 的效果，需要在配置的注入样式或自定义 CSS 中自行声明规则。 :::

常用属性简写

.class-name：等价于 class="class-name"
#id-name：等价于 id="id-name"
key="value"：直接设定 HTML 属性

这是一段强调说明。{.lead-text}

### 章节标题 {#section-anchor}

![配图](./cover.webp){loading="lazy" width="720"}

同一元素需要多个属性时可以连续书写，简写与键值对可混用：

==混合写法=={.secondary #highlight-1 title="鼠标悬停提示"}

渲染效果：==混合写法=={.secondary #highlight-1 title="鼠标悬停提示"}

与容器语法的配合

所有 ::: 容器都支持在标题后追加属性字典，这让同一类容器可以承载不同的样式角色：

::: warning[构建前请检查]{class="build-warning"}
未通过 `astro check` 的提交不会进入部署流水线。
:::

渲染效果：

::: warning[构建前请检查]{class="build-warning"} 未通过 astro check 的提交不会进入部署流水线。 :::

小结

书写位置	适用对象	典型用途
行内元素之后	链接、`==高亮==`、行内代码	注入 `target`、语义 class
标题之后	`#` ~ `######` 标题	固定锚点 id，方便站外引用
容器标题之后	`:::` 各类容器	挂载自定义样式类

属性字典是纯构建期语法，不会带来任何客户端运行时开销。

基础语法

Fri, 18 Sep 2026 00:00:00 GMT

Markdown 是一种轻量级标记语言，通过简洁直观的标记语法让纯文本具备格式化排版能力。Shirone 原生支持完整的 CommonMark 与 GFM 规范，你在 GitHub、Typora 或 VS Code 中写下的标记几乎都能原样生效。

本文把标准语法拆成块级元素、行内元素与辅助转义三部分，每段示例下方都给出真实渲染结果，方便对照查阅。

一、块级元素

1. 段落与换行

段落：由连续文本行组成，段落之间通过一个或多个空行分隔。
强制换行：在行尾添加两个或以上空格后回车，或者在行尾使用反斜线 \ 后回车。

这是第一行文本，行尾加两个空格  
这是同一段落内的强制换行。

这是新段落，与上一段之间保留了空行。

渲染效果：

这是第一行文本，行尾加两个空格
这是同一段落内的强制换行。

这是新段落，与上一段之间保留了空行。

2. 标题

推荐使用标准的 Atx 井号语法，支持 1 到 6 级标题：

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

构建阶段会自动为各级标题生成语义锚点，并自动提取到文章右侧的目录导航中。

渲染效果（文章顶部的一级标题由主题接管，正文中从二级开始使用）：

四级标题示例

五级标题示例

六级标题示例

3. 引用块

在行首使用 > 符号声明引用，支持多层嵌套以及在引用内部嵌入列表、代码和标题：

> 这是第一层引用内容。
>
> > 这是嵌套的第二层引用。
>
> 引用内部支持列表与格式化：
> 1. 第一项说明
> 2. 第二项说明
>
> `引用内的行内代码`

渲染效果：

这是第一层引用内容。

这是嵌套的第二层引用。

引用内部支持列表与格式化：

第一项说明

第二项说明

引用内的行内代码

4. 列表与任务清单

无序列表

使用 -、* 或 + 开头（推荐统一使用 -），标记符号与文本之间必须保留空格：

- 无序列表项一
- 无序列表项二
  - 缩进两个空格形成子列表
  - 第二个子列表项

渲染效果：

无序列表项一
无序列表项二
- 缩进两个空格形成子列表
- 第二个子列表项

有序列表

使用数字加英文句点 1. 开头：

1. 第一步操作
2. 第二步操作
3. 第三步操作

渲染效果：

第一步操作
第二步操作
第三步操作

任务清单

使用方括号标注任务状态：

- [x] 已完成的核心配置项
- [ ] 待编写的技术文档章节
- [ ] 待确认的排版细节

渲染效果：

[x] 已完成的核心配置项
[ ] 待编写的技术文档章节
[ ] 待确认的排版细节

5. 代码块

使用三个反引号包裹多行代码，并在首行声明编程语言：

```typescript
interface SiteConfig {
  title: string;
  themeColor: number;
}
```

渲染效果：

interface SiteConfig {
  title: string;
  themeColor: number;
}

6. 水平分割线

单独成行使用三个或以上的 -、* 或 _ 创建分割线：

段落上部内容

---

段落下部内容

渲染效果：

段落上部内容

段落下部内容

二、行内元素

1. 文本强调

*斜体文本*
**粗体文本**
***粗斜体文本***
~~删除线文本~~
`行内代码`

渲染效果：斜体文本、粗体文本、粗斜体文本、~~删除线文本~~、行内代码

2. 超链接

行内式链接

[链接文字](https://shirone.mysqil.com/ "可选的悬停提示标题")
[站内相对路径](/guide/intro/)

渲染效果：链接文字、站内相对路径

参考式链接

适合在长文中多次引用同一地址：

详细规范请参考 [官方文档][docs] 和 [仓库地址][repo]。

[docs]: https://shirone.mysqil.com/ "文档站"
[repo]: https://github.com/LyraVoid/Shirone "GitHub"

渲染效果：详细规范请参考官方文档和仓库地址。

3. 图片插入

语法与超链接类似，只需在最前方添加感叹号 !：

![图片替代文本](./scene-2.webp "可选图题")

图片与 index.md 放在同一个文章文件夹中，使用相对路径引用即可，构建期会自动压缩为 WebP 并生成响应式 srcset。

渲染效果：

4. 自动链接

使用尖括号包裹网址或邮箱，系统会自动转换为可点击链接：

<https://shirone.mysqil.com>
<contact@example.com>

渲染效果：https://shirone.mysqil.com、contact@example.com

三、常用辅助与转义

1. 转义字符

当需要直接输出 Markdown 保留符号时，在符号前添加反斜线 \ 进行转义：

\*这不是斜体文本\*
\[这不是链接\]
\# 这不是标题

渲染效果：*这不是斜体文本*、[这不是链接]、# 这不是标题

可转义的字符包括：\、`、*、_、{}、[]、()、#、+、-、.、!。

2. 原生 HTML 支持

Markdown 允许直接内嵌标准 HTML 标签（如 <kbd>、<span>、<details>）：

使用 <kbd>Ctrl</kbd> + <kbd>C</kbd> 复制内容。

<div style="text-align: center;">
  居中显示的纯 HTML 说明文本
</div>

渲染效果：使用 <kbd>Ctrl</kbd> + <kbd>C</kbd> 复制内容。

<div style="text-align: center;"> 居中显示的纯 HTML 说明文本 </div>

3. 编辑器快捷键对照

排版效果	语法格式	Windows / Linux 快捷键	macOS 快捷键
粗体	`文本`	Ctrl + B	Command + B
斜体	`文本`	Ctrl + I	Command + I
行内代码	`代码`	Ctrl + Shift + `	Command + Shift + `
插入链接	`[文本](链接)`	Ctrl + K	Command + K
插入图片	`![说明](路径)`	Ctrl + Shift + I	Command + Shift + I

四、排版建议与最佳实践

中文排版间距：中文字符与英文字符、数字之间建议保留一个半角空格，提升可读性。
标点规范：中文句子中使用全角中文标点，英文句子与代码中严格使用半角标点。
图片格式：推荐优先使用 WebP 或 AVIF 格式图片，兼顾画质与加载速度。

::: tip 下一步标准语法之上，Shirone 还提供了一整套扩展语法与属性字典，请继续阅读扩展与属性。 :::

C++ 代码格式化配置详解

Mon, 11 Feb 2019 00:00:00 GMT

代码格式化的意义

很多人编写程序时不注意程序的版式结构，这样做虽然不会影响程序的功能，但是程序的可读性会大大降低。

C++ 语言的格式很自由，这意味着换行、空格、空行和制表符等空白在程序运行时都会被忽略，程序员可以使用空白让代码按照特定的风格缩进或分开，使程序更加清晰易懂。

个人认为，在 OI 考场上，一个优秀的码风可以有些提高你的调试效率。

假设我们写的是文章而不是程序，那么你一定觉得诸如文章应该分为若干个自然段、每段开头空两格之类的规则是理所当然的。如果段落的开头不空两格，或者干脆把整个文章写成单独的一段，仔细想来似乎也不会影响文章实质内容的表达。既然如此，我们为什么还要在形式上下功夫呢？设想一下，如果你手中的这本书既无章节也无目录，正文中的不同内容都使用同样的字体字号印刷，几百页纸从头至尾洋洋洒洒如念经般地“一气呵成”，你还有耐心看下去吗？

这是一个人人都能理解的道理，可是当文章变成程序的时候，就不是每个人都能想得通的了。不仅仅是初学者，甚至一些熟练的开发人员，也会写出凌乱不堪的代码。许多人一定有过这样的经历：一年半载之后，自己原来写的程序就完全看不懂了。如果这段程序只是为了交作业，或者临时一用，那还可以不去追究，但如果这是一个商业软件，现在需要根据客户的要求进行修改的话，工作量可就大了——你不得不先花时间把你原来的思路看懂。

肯定会有人反驳：代码是给机器运行的，又不是给人看的，写那么好看有什么用？

他的话只对了前半句：代码确实是给机器运行的，可是机器总共才需要看它几分钟？你花一个月编写的程序，机器顶多两三分钟就编译好了——在这两三分钟之前，这代码不都是你在看吗？开发软件编写代码不是一朝一夕的事情，更多的情况下，一个软件的开发要经历很长的时间，并且常常由多人合作完成。一个庞大的软件项目，可能会动用上千名程序员工作数年！如果把代码写得连自己都看不明白，怎么与别人交流？同一个开发团队内，一定要保持良好且一致的代码风格，才能最大化地提高开发效率。

代码格式化演示

感谢 @xlj2596 提供的洛谷 P3371代码，评测记录：R16227912。

格式化前代码

// luogu-judger-enable-o2
#include<cstdio>
#include<cstring>
#include<algorithm>
const int maxm=10005;
const int maxn=500005;
using namespace std;
bool vis[maxm];
int N,M,S,F,G,W,_start,_end,_size,Q[4000005],f[maxm],to[maxn<<1],val[maxn<<1],nxt[maxn<<1],las[maxn<<1];
inline void addedge(int x,int y,int z){_size++;to[_size]=y;val[_size]=z;nxt[_size]=las[x];las[x]=_size;}
inline void spfa(){
    _end=1;_start=1;f[S]=0;Q[1]=S;
    memset(f,63,sizeof(f));
    while(_start<=_end){
        int x=Q[_start++];
        vis[x]=false;//已经访问 
        for(int i=las[x];i;i=nxt[i]){
            if(f[x]+val[i]<f[to[i]]){
                f[to[i]]=f[x]+val[i];
                if(!vis[to[i]]){
                    vis[to[i]]=true;
                    Q[++_end]=to[i];
                }
            }
        }
    }
}
int main(){
    scanf("%d%d%d",&N,&M,&S);
    for(int i=1;i<=M;i++){scanf("%d%d%d",&F,&G,&W);addedge(F,G,W);}
    spfa();
    for(int i=1;i<=N;i++){
        printf("%d%c",f[i]>1e9?2147483647:f[i],i==N?'\n':' ');
        //if(f[i]>1e9)printf("2147483647 ");
        //else printf("%d ",f[i]);
        //printf("%d ",f[i]>1e9?2147483647:f[i]);
        
    }
    return 0;
}

格式化后代码

#include <algorithm>
#include <cstdio>
#include <cstring>
const int maxm = 10005;
const int maxn = 500005;
using namespace std;
bool vis[ maxm ];
int N, M, S, F, G, W, _start, _end, _size, Q[ 4000005 ], f[ maxm ],
    to[ maxn << 1 ], val[ maxn << 1 ], nxt[ maxn << 1 ], las[ maxn << 1 ];
inline void addedge( int x, int y, int z ) {
    _size++;
    to[ _size ] = y;
    val[ _size ] = z;
    nxt[ _size ] = las[ x ];
    las[ x ] = _size;
}
inline void spfa() {
    _end = 1;
    _start = 1;
    f[ S ] = 0;
    Q[ 1 ] = S;
    memset( f, 63, sizeof( f ) );
    while ( _start <= _end ) {
        int x = Q[ _start++ ];
        vis[ x ] = false;  //已经访问
        for ( int i = las[ x ]; i; i = nxt[ i ] ) {
            if ( f[ x ] + val[ i ] < f[ to[ i ] ] ) {
                f[ to[ i ] ] = f[ x ] + val[ i ];
                if ( !vis[ to[ i ] ] ) {
                    vis[ to[ i ] ] = true;
                    Q[ ++_end ] = to[ i ];
                }
            }
        }
    }
}
int main() {
    scanf( "%d%d%d", &N, &M, &S );
    for ( int i = 1; i <= M; i++ ) {
        scanf( "%d%d%d", &F, &G, &W );
        addedge( F, G, W );
    }
    spfa();
    for ( int i = 1; i <= N; i++ ) {
        printf( "%d%c", f[ i ] > 1e9 ? 2147483647 : f[ i ],
                i == N ? '\n' : ' ' );
        // if(f[i]>1e9)printf("2147483647 ");
        // else printf("%d ",f[i]);
        // printf("%d ",f[i]>1e9?2147483647:f[i]);
    }
    return 0;
}

C++

对于 C++，普遍使用 clang-format 来格式化代码，当然，你也可以选择 Visual Studio 自带的格式化功能。这里不介绍 Visual Studio 的安装，请自行查阅官方文档。

如何安装 `clang-format`

`Windows` 玩家

只下载 `clang-format` 程序

建议直接下载 clang-format 可执行文件。官方发布页（LLVM Releases 或 GitHub Releases）提供各平台的独立压缩包，解压后即可使用。

你可以使用命令行来调用程序，详见 ClangFormat 官方文档。

下载 `Clang` 提供完整体验

clang-format 程序作为 Clang 的一部分，你可以选择下载整个包以获得完整体验。

:::info Clang 是一个 C 语言、C++、Objective-C 语言的轻量级编译器，源代码发布于 BSD 协议下。截至 2026 年 10 月，LLVM/Clang 的最新稳定版为 23.1.x；本文最初写作时的版本是 11.0.1，配置项名称在后续版本中有较多调整，详见下文。 :::

VSCode 玩家

在扩展（插件）页面安装 C/C++ 扩展（ms-vscode.cpptools，旧称 cpptools），你就可以对选中代码块使用 Ctrl+K Ctrl+F 来格式化代码，或者用 Shift+Alt+F 格式化整个文件。

`Ubuntu` 玩家

sudo apt install clang-format

RHEL 系发行版玩家（CentOS / Rocky Linux / AlmaLinux）

sudo dnf install clang-tools-extra

:::warning CentOS Linux 7 已于 2024 年 6 月停止维护，CentOS Linux 8 更早在 2021 年底终止，因此不建议再在新环境中使用 CentOS，可以改用 Rocky Linux、AlmaLinux 等下游发行版。另外，RHEL 系仓库中并没有名为 clang-format 的包，该程序由 clang-tools-extra 包提供（旧文中的 sudo yum install clang-format 无法安装成功）。 :::

:::tip 安装完成后，你就可以开始下一步操作了。 :::

配置你的代码风格

本实验基于 Windows 10 x64 1809 专业版 & VSCode 1.31.0（2019 年写作时的环境，操作方式在后来的版本中基本一致）。

基于上述方法安装后，你可以打开一个文件夹，如下图所示。

新建一个文件，叫做 .clang-format 或者 _clang-format。

:::note 在 Linux 文件系统中，以一个英文句点开始的文件名的文件具有隐藏属性，所以你可能需要调整设置以显示它。 :::

:::info Windows 玩家可能发现自己使用资源管理器无法新建以这个名字命名的文件，请使用命令行或 VSCode。 :::

然后打开这个文件，就像这样。

输入你的配置文件，保存并关闭。

这样你就可以使用代码格式化了：选中你要格式化的部分并按下 Ctrl+K Ctrl+F 格式化选区，或者按下 Shift+Alt+F 格式化全文。

:::note 此处的 Ctrl+K Ctrl+F 是指先按 Ctrl+K，再按 Ctrl+F。你可以在「文件 → 首选项 → 键盘快捷方式」里修改快捷键。 :::

配置文件的书写

模板

:::warning 下面的模板来自 2019 年，部分选项在后续的 clang-format 中已被重命名、改为枚举或废弃。模板里已经就地修正了这些写法（如 AlignEscapedNewlinesLeft、AlwaysBreakAfterReturnType、AlwaysBreakTemplateDeclarations、ConstructorInitializerAllOnOneLineOrOnePerLine、BreakConstructorInitializersBeforeComma、AlignAfterOpenBracket、AlignOperands、SpacesInAngles、AllowShortBlocksOnASingleLine、AllowShortIfStatementsOnASingleLine、Cpp11BracedListStyle、BraceWrapping.AfterControlStatement），并在注释里标注了对应关系。若你使用的是较旧的 clang-format，请以官方文档对应版本为准。 :::

::: details 配置文件

---
# 语言: None, Cpp, Java, JavaScript, ObjC, Proto, TableGen, TextProto
Language:	Cpp
# BasedOnStyle:	LLVM
# 访问说明符(public、private等)的偏移
AccessModifierOffset:	-4
# 开括号(开圆括号、开尖括号、开方括号)后的对齐
# clang-format 22 起该选项改为布尔值：Align→true、DontAlign→false，
# AlwaysBreak 由 BreakAfterOpenBracket* 等新选项取代
AlignAfterOpenBracket:	true
# 连续赋值时，对齐所有等号
AlignConsecutiveAssignments:	true
# 连续声明时，对齐所有声明的变量名
AlignConsecutiveDeclarations:	false
# 左对齐逃脱换行(使用反斜杠换行)的反斜杠: DontAlign, Left, LeftWithLastLine, Right
# 旧版写作 AlignEscapedNewlinesLeft: true，该写法已被移除
AlignEscapedNewlines:	Left
# 水平对齐二元和三元表达式的操作数: DontAlign, Align, AlignAfterOperator
AlignOperands:	Align
# 对齐连续的尾随的注释
AlignTrailingComments:	true
# 允许函数声明的所有参数在放在下一行
AllowAllParametersOfDeclarationOnNextLine:	true
# 允许短的块放在同一行: Never, Empty, Always
AllowShortBlocksOnASingleLine:	Never
# 允许短的case标签放在同一行
AllowShortCaseLabelsOnASingleLine:	false
# 允许短的函数放在同一行: None, InlineOnly(定义在类中), Empty(空函数), Inline(定义在类中，空函数), All
AllowShortFunctionsOnASingleLine:	Empty
# 允许短的if语句保持在同一行: Never, WithoutElse, OnlyFirstIf, AllIfsAndElse
AllowShortIfStatementsOnASingleLine:	Never
# 允许短的循环保持在同一行
AllowShortLoopsOnASingleLine:	false
# 总是在返回类型后换行: None, All, TopLevel(顶级函数，不包括在类中的函数),
#   AllDefinitions(所有的定义，不包括声明), TopLevelDefinitions(所有的顶级函数的定义)
# 旧版写作 AlwaysBreakAfterReturnType / AlwaysBreakAfterDefinitionReturnType，两者均已废弃
BreakAfterReturnType:	None
# 总是在多行string字面量前换行
AlwaysBreakBeforeMultilineStrings:	false
# 总是在template声明后换行: Leave, No, MultiLine, Yes
# 旧版写作 AlwaysBreakTemplateDeclarations: false，已废弃
BreakTemplateDeclarations:	No
# false表示函数实参要么都在同一行，要么都各自一行
BinPackArguments:	true
# false表示所有形参要么都在同一行，要么都各自一行
BinPackParameters:	true
# 在大括号前换行: Attach(始终将大括号附加到周围的上下文), Linux(除函数、命名空间和类定义，与Attach类似),
#   Mozilla(除枚举、函数、记录定义，与Attach类似), Stroustrup(除函数定义、catch、else，与Attach类似),
#   Allman(总是在大括号前换行), GNU(总是在大括号前换行，并对于控制语句的大括号增加额外的缩进), WebKit(在函数前换行), Custom
#   注：这里认为语句块也属于函数
BreakBeforeBraces:	Custom
# 大括号换行，只有当BreakBeforeBraces设置为Custom时才有效
BraceWrapping:   
    # class定义后面
    AfterClass:	false
    # 控制语句后面: Never, MultiLine, Always（旧版为布尔值 false，已废弃）
    AfterControlStatement:	Never
    # enum定义后面
    AfterEnum:	false
    # 函数定义后面
    AfterFunction:	false
    # 命名空间定义后面
    AfterNamespace:	false
    # ObjC定义后面
    AfterObjCDeclaration:	false
    # struct定义后面
    AfterStruct:	false
    # union定义后面
    AfterUnion:	false
    # catch之前
    BeforeCatch:	false
    # else之前
    BeforeElse:	true
    # 缩进大括号
    IndentBraces:	false
# 在二元运算符前换行: None(在操作符后换行), NonAssignment(在非赋值的操作符前换行), All(在操作符前换行)
BreakBeforeBinaryOperators:	NonAssignment
# 在三元运算符前换行
BreakBeforeTernaryOperators:	true
# 在构造函数的初始化列表的逗号前换行
# 旧版写作 BreakConstructorInitializersBeforeComma: false，已废弃，对应 BeforeColon
BreakConstructorInitializers:	BeforeColon
# 每行字符的限制，0表示没有限制
ColumnLimit:	80
# 描述具有特殊意义的注释的正则表达式，它不应该被分割为多行或以其它方式改变
CommentPragmas:	'^ IWYU pragma:'
# 构造函数的初始化列表的打包方式: Never, BinPack, CurrentLine, NextLine
# 旧版写作 ConstructorInitializerAllOnOneLineOrOnePerLine: false，已废弃，对应 BinPack
PackConstructorInitializers:	BinPack
# 构造函数的初始化列表的缩进宽度
ConstructorInitializerIndentWidth:	4
# 延续的行的缩进宽度
ContinuationIndentWidth:	4
# 去除C++11的列表初始化的大括号{后和}前的空格: Block, FunctionCall
Cpp11BracedListStyle:	Block
# 继承最常用的指针和引用的对齐方式
DerivePointerAlignment:	false
# 关闭格式化
DisableFormat:	false
# 自动检测函数的调用和定义是否被格式为每行一个参数(Experimental)
ExperimentalAutoDetectBinPacking:	false
# 需要被解读为foreach循环而不是函数调用的宏
ForEachMacros:	[ foreach, Q_FOREACH, BOOST_FOREACH ]
# 对#include进行排序，匹配了某正则表达式的#include拥有对应的优先级，匹配不到的则默认优先级为INT_MAX(优先级越小排序越靠前)，
#   可以定义负数优先级从而保证某些#include永远在最前面
IncludeCategories: 
  - Regex:	'^"(llvm|llvm-c|clang|clang-c)/'
    Priority:	2
  - Regex:	'^(<|"(gtest|isl|json)/)'
    Priority:	3
  - Regex:	'.*'
    Priority:	1
# 缩进case标签
IndentCaseLabels:	false
# 缩进宽度
IndentWidth:	4
# 函数返回类型换行时，缩进函数声明或函数定义的函数名
IndentWrappedFunctionNames:	false
# 保留在块开始处的空行（新版改用 KeepEmptyLines.AtStartOfBlock，本项已废弃）
KeepEmptyLinesAtTheStartOfBlocks:	true
# 开始一个块的宏的正则表达式
MacroBlockBegin:	''
# 结束一个块的宏的正则表达式
MacroBlockEnd:	''
# 连续空行的最大数量
MaxEmptyLinesToKeep:	1
# 命名空间的缩进: None, Inner(缩进嵌套的命名空间中的内容), All
NamespaceIndentation:	Inner
# 使用ObjC块时缩进宽度
ObjCBlockIndentWidth:	4
# 在ObjC的@property后添加一个空格
ObjCSpaceAfterProperty:	false
# 在ObjC的protocol列表前添加一个空格
ObjCSpaceBeforeProtocolList:	true
# 在call(后对函数调用换行的penalty
PenaltyBreakBeforeFirstCallParameter:	19
# 在一个注释中引入换行的penalty
PenaltyBreakComment:	300
# 第一次在<<前换行的penalty
PenaltyBreakFirstLessLess:	120
# 在一个字符串字面量中引入换行的penalty
PenaltyBreakString:	1000
# 对于每个在行字符数限制之外的字符的penalty
PenaltyExcessCharacter:	80
# 将函数的返回类型放到它自己的行的penalty
PenaltyReturnTypeOnItsOwnLine:	80
# 指针和引用的对齐: Left, Right, Middle
PointerAlignment:	Left
# 允许重新排版注释
ReflowComments:	true
# 允许排序#include
SortIncludes:	true
# 在C风格类型转换后添加空格
SpaceAfterCStyleCast:	false
# 在赋值运算符之前添加空格
SpaceBeforeAssignmentOperators:	true
# 开圆括号之前添加一个空格: Never, ControlStatements, ControlStatementsExceptControlMacros, NonEmptyParentheses, Always
SpaceBeforeParens:	ControlStatements
# 在空的圆括号中添加空格
SpaceInEmptyParentheses:	false
# 在尾随的评论前添加的空格数(只适用于//)
SpacesBeforeTrailingComments:	2
# 在尖括号的<后和>前添加空格: Never, Always, Leave
SpacesInAngles:	Always
# 在容器(ObjC和JavaScript的数组和字典等)字面量中添加空格
SpacesInContainerLiterals:	true
# 在C风格类型转换的括号中添加空格（新版改用 SpacesInParens.InCStyleCasts，本项已废弃）
SpacesInCStyleCastParentheses:	true
# 在圆括号的(后和)前添加空格
SpacesInParentheses:	true
# 在方括号的[后和]前添加空格，lamda表达式和未指明大小的数组的声明不受影响
SpacesInSquareBrackets:	true
# 标准: Cpp03, Cpp11, Cpp14, Cpp17, Cpp20, Cpp23, Latest, Auto
Standard:	Cpp11
# tab宽度
TabWidth:	4
# 使用tab字符: Never, ForIndentation, ForContinuationAndIndentation, Always
UseTab:	Never

:::

语法

配置文件使用 YAML 语法，大抵概括如下：

所有的注释以 # 开头。
所有的值以 Key: Value 形式出现，每行一个，冒号是英文冒号，冒号后面空一格或者一个 Tab。
同一个配置文件里不能出现重复的键（后出现的会覆盖先出现的，容易埋坑）。

参数解释

这里只解释一些容易出现错误或者混淆的参数，其余参数，请参见 Clang 格式样式选项或阅读附图上的谷歌翻译后的文档。如果阅读后还有异议，请在下方评论，博主会酌情回答和解释。

易出现错误或者混淆的参数

Language：字符串，取值范围。该配置文件针对的语言。请填写 Cpp，不是 cpp、cpp11、C++、kkkAKIOI 等。
- None：不要使用。
- Cpp：C，C++。
- Java：Java。
- JavaScript：JavaScript。
- ObjC：Objective-C，Objective-C++。
- Proto：协议缓冲区。
- TableGen：TableGen。
- TextProto：文本格式的协议缓冲消息。
BasedOnStyle：字符串，取值范围。基于的语言。点击链接可以查看内容和效果。当你没有配置值的时候，参考你所选择的标准。
- LLVM
- Google
- Chromium
- Mozilla
- WebKit
- Microsoft
- GNU
AccessModifierOffset：整型。（public、private 等）访问说明符的偏移，如下图。一般用不到。
AlignAfterOpenBracket：开括号（开圆括号、开尖括号、开方括号）后的对齐方式。
- 旧版取值为 Align（对齐到开括号后的参数）、DontAlign（不做对齐）、AlwaysBreak（参数不适合单行时在开括号后换行）。
- clang-format 22 起该选项改为布尔值：Align 等价于 true，DontAlign 等价于 false；AlwaysBreak 的行为改由 BreakAfterOpenBracketFunction、BreakAfterOpenBracketBracedList、BreakAfterOpenBracketIf 等新选项控制，闭合括号一侧对应 BreakBeforeCloseBracket*。
- Align（旧版，现为 true）：对齐打开括号上的参数
  
  e.g.
```
someLongFunction(argument1,
                 argument2);
```
- DontAlign（旧版，现为 false）：不用对齐
  
  e.g.
```
someLongFunction(argument1,
	argument2);
```
- AlwaysBreak：如果参数不适合单行，则在开括号后断开
  
  e.g.
```
someLongFunction(
	argument1, argument2);
```
AlignConsecutiveAssignments：布尔值。对齐连续分配。如果取值为真，对齐连续行的赋值运算符。

e.g.
```
int kkk  = 666;
int cz   = 888;
int c    = 999;
```
AlignConsecutiveDeclarations：布尔值。如果取值为真，对齐连续行的声明名称。

e.g.
```
int         aaaa = 12;
float       b = 23;
std::string ccc = 23;
```

Clang 格式样式选项全文档

图的尺寸 1903×31205，约 2.5 MB，强烈建议直接右键另存为下来慢慢看。