<?xml version="1.0" encoding="UTF-8"?><rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Shirone</title><description>A Material 3 anime blog</description><link>https://blog.0x2d1.us.kg/</link><language>zh_CN</language><item><title>Markdown 语法全量测试</title><link>https://blog.0x2d1.us.kg/posts/markdown-syntax-test/</link><guid isPermaLink="true">https://blog.0x2d1.us.kg/posts/markdown-syntax-test/</guid><description>单篇文章逐项跑通 Shirone 的全部自定义 Markdown 语法与 Expressive Code 元数据，用于验收渲染、降级与按需加载行为。</description><pubDate>Wed, 16 Sep 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;本文是站点的语法验收页：每一节都在正文里&lt;strong&gt;真实使用&lt;/strong&gt;一种语法，而不是把语法写进代码块里当文档。哪一项渲染不对，直接定位到对应小节即可。&lt;/p&gt;
&lt;p&gt;*[SSR]: Server-Side Rendering
*[LCP]: Largest Contentful Paint
*[CLS]: Cumulative Layout Shift&lt;/p&gt;
&lt;h2&gt;1. 基础 Markdown 与 GFM&lt;/h2&gt;
&lt;p&gt;普通段落支持 &lt;em&gt;斜体&lt;/em&gt;、&lt;strong&gt;粗体&lt;/strong&gt;、&lt;em&gt;&lt;strong&gt;粗斜体&lt;/strong&gt;&lt;/em&gt;、&lt;s&gt;删除线&lt;/s&gt;、&lt;code&gt;行内代码&lt;/code&gt;，以及指向 &lt;a href=&quot;https://docs.astro.build/&quot;&gt;Astro 官方文档&lt;/a&gt; 的链接和自动链接 https://astro.build/。&lt;/p&gt;
&lt;h3&gt;列表&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;无序列表项&lt;/li&gt;
&lt;li&gt;第二项
&lt;ul&gt;
&lt;li&gt;嵌套子项&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;第三项&lt;/li&gt;
&lt;/ul&gt;
&lt;ol&gt;
&lt;li&gt;有序列表项&lt;/li&gt;
&lt;li&gt;第二项&lt;/li&gt;
&lt;li&gt;第三项&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;任务列表&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;[x] 已完成的事项&lt;/li&gt;
&lt;li&gt;[ ] 待办事项&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;引用与分隔线&lt;/h3&gt;
&lt;blockquote&gt;
&lt;p&gt;引用可以跨段。&lt;/p&gt;
&lt;p&gt;引用内部的 &lt;strong&gt;Markdown&lt;/strong&gt; 依然生效。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;hr /&gt;
&lt;h3&gt;表格&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;语法&lt;/th&gt;
&lt;th&gt;入口类型&lt;/th&gt;
&lt;th&gt;运行时成本&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;admonition&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;container&lt;/td&gt;
&lt;td&gt;原生，无 JS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;mermaid&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;fence&lt;/td&gt;
&lt;td&gt;按需加载客户端模块&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;math&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;inline-extension&lt;/td&gt;
&lt;td&gt;构建期生成，无 JS&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;行内代码与围栏&lt;/h3&gt;
&lt;p&gt;反引号里的内容保持字面量：&lt;code&gt;==这不是高亮==&lt;/code&gt;、&lt;code&gt;:spoiler[这不是剧透]&lt;/code&gt;、&lt;code&gt;[+也不是标注]&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;2. 提示容器 Admonition&lt;/h2&gt;
&lt;p&gt;三种写法等价：带方括号标题、带空格标题、以及 GitHub Alert 引用语法。&lt;/p&gt;
&lt;p&gt;:::note
&lt;code&gt;note&lt;/code&gt;：即便读者只是快速扫读，也需要留意的信息。
:::&lt;/p&gt;
&lt;p&gt;:::info[带方括号的自定义标题]
标题写在方括号里，正文支持完整 Markdown，例如列表与 &lt;code&gt;行内代码&lt;/code&gt;。
:::&lt;/p&gt;
&lt;p&gt;:::tip
&lt;code&gt;tip&lt;/code&gt;：帮助读者更顺利完成操作的可选信息。
:::&lt;/p&gt;
&lt;p&gt;:::important
&lt;code&gt;important&lt;/code&gt;：读者必须知道才能成功的关键信息。
:::&lt;/p&gt;
&lt;p&gt;::: warning 带空格的自定义标题
&lt;code&gt;warning&lt;/code&gt;：需要立即关注、存在风险的内容。
:::&lt;/p&gt;
&lt;p&gt;:::caution
&lt;code&gt;caution&lt;/code&gt;：操作可能带来负面后果。
:::&lt;/p&gt;
&lt;p&gt;:::details[折叠详情]
&lt;code&gt;details&lt;/code&gt; 使用原生 &lt;code&gt;&amp;lt;details&amp;gt;&lt;/code&gt;，无 hydration、无客户端模块、无网络请求。
:::&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;[!NOTE]
GitHub Alert 语法会汇入同一套 Admonition 渲染器。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;3. 折叠面板 Collapse Panels&lt;/h2&gt;
&lt;h3&gt;独立开合&lt;/h3&gt;
&lt;p&gt;每项默认独立开合。标题前加 &lt;code&gt;:+&lt;/code&gt; 表示初始展开，&lt;code&gt;:-&lt;/code&gt; 表示初始收起。&lt;/p&gt;
&lt;p&gt;::: collapse&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;依赖要求&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;使用 Node.js 22 或更新版本，并在安装依赖前启用 Corepack。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;:+ 安装依赖&lt;/p&gt;
&lt;p&gt;在仓库根目录执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd install
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;运行校验&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;pnpm.cmd check:manifest&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;npx.cmd astro check&lt;/code&gt;
:::&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;手风琴模式&lt;/h3&gt;
&lt;p&gt;加 &lt;code&gt;accordion&lt;/code&gt; 后同一组内只保留一个展开项；&lt;code&gt;expand&lt;/code&gt; 让首个面板默认展开。&lt;/p&gt;
&lt;p&gt;::: collapse accordion expand&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;这个面板为什么默认展开？&lt;/p&gt;
&lt;p&gt;因为容器声明了 &lt;code&gt;expand&lt;/code&gt;，且没有任何项带 &lt;code&gt;:+&lt;/code&gt; 标记。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;标题里能有 Markdown 吗？&lt;/p&gt;
&lt;p&gt;可以。标题支持 &lt;strong&gt;强调&lt;/strong&gt; 与 &lt;code&gt;代码&lt;/code&gt;，面板正文支持完整块级 Markdown。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;窄屏表现如何？&lt;/p&gt;
&lt;p&gt;内边距收窄、长文本换行，内嵌代码保持自己的横向滚动区域。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;4. 选项组 Option Groups&lt;/h2&gt;
&lt;p&gt;同一个 &lt;code&gt;#id&lt;/code&gt; 的多个选项组会跨页同步，选择结果也会被记住。&lt;/p&gt;
&lt;p&gt;::: tabs#package-manager&lt;/p&gt;
&lt;p&gt;@tab npm&lt;/p&gt;
&lt;p&gt;使用 npm 安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npm install astro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@tab:active &lt;strong&gt;pnpm&lt;/strong&gt;#pnpm&lt;/p&gt;
&lt;p&gt;使用 pnpm 安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd add astro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@tab Bun#bun&lt;/p&gt;
&lt;p&gt;使用 Bun 安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;bun add astro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;p&gt;下面这组共用 &lt;code&gt;package-manager&lt;/code&gt;，选择上面任一选项会同步切换这里。&lt;/p&gt;
&lt;p&gt;::: tabs#package-manager&lt;/p&gt;
&lt;p&gt;@tab npm&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npm run dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@tab pnpm&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@tab Bun#bun&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;bun run dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h2&gt;5. 步骤流 Steps&lt;/h2&gt;
&lt;h3&gt;属性标题&lt;/h3&gt;
&lt;p&gt;容器内必须恰好包含一个有序列表，每个顶层列表项就是一个步骤。&lt;/p&gt;
&lt;p&gt;:::steps{title=&quot;本地验收流程&quot;}&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;准备环境&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;克隆仓库并安装依赖。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd install
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;运行诊断&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;确认 Astro 诊断与清单校验全部通过。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx.cmd astro check
pnpm.cmd check:manifest
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;构建产物&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;生成静态站点与搜索索引。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd build
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h3&gt;方括号标题&lt;/h3&gt;
&lt;p&gt;:::steps[快速开始]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;安装依赖&lt;/li&gt;
&lt;li&gt;启动开发服务器&lt;/li&gt;
&lt;li&gt;打开 &lt;a href=&quot;http://localhost:4321&quot;&gt;http://localhost:4321&lt;/a&gt;
:::&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;6. 代码树 Code Tree&lt;/h2&gt;
&lt;h3&gt;容器写法&lt;/h3&gt;
&lt;p&gt;每个围栏用 &lt;code&gt;title=&quot;路径&quot;&lt;/code&gt; 声明自己在树中的位置。&lt;/p&gt;
&lt;p&gt;:::code-tree{title=&quot;语法测试样例&quot; height=&quot;380px&quot; entry=&quot;src/greet.ts&quot;}&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export function greet(name: string): string {
	return `Hello, ${name}`;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;{
	&quot;name&quot;: &quot;greet-demo&quot;,
	&quot;version&quot;: &quot;1.0.0&quot;,
	&quot;type&quot;: &quot;module&quot;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;import { greet } from &quot;./greet.ts&quot;;

console.log(greet(&quot;Shirone&quot;));
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h3&gt;目录自动导入&lt;/h3&gt;
&lt;p&gt;指向仓库内目录即可在构建期扫描生成，无需手工复制文件内容。&lt;/p&gt;
&lt;p&gt;@&lt;a href=&quot;/src/utils/music&quot;&gt;code-tree title=&quot;音乐工具模块&quot; entry=&quot;playlist.ts&quot;&lt;/a&gt;&lt;/p&gt;
&lt;h2&gt;7. 文件树 File Tree&lt;/h2&gt;
&lt;h3&gt;嵌套列表写法&lt;/h3&gt;
&lt;p&gt;目录以结尾斜杠标记为默认收起，&lt;code&gt;++&lt;/code&gt; / &lt;code&gt;--&lt;/code&gt; 标记新增与删除，&lt;code&gt;#&lt;/code&gt; 之后是行内注释，&lt;code&gt;**粗体**&lt;/code&gt; 用于强调关键文件。&lt;/p&gt;
&lt;p&gt;:::file-tree{title=&quot;站点内容结构&quot;}&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;src
&lt;ul&gt;
&lt;li&gt;components/
&lt;ul&gt;
&lt;li&gt;++ SideBar.astro # 侧栏编排入口&lt;/li&gt;
&lt;li&gt;-- OldWidget.svelte # 已下线组件&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;content
&lt;ul&gt;
&lt;li&gt;posts/
&lt;ul&gt;
&lt;li&gt;markdown-syntax-test.md&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;snippets/
&lt;ul&gt;
&lt;li&gt;include-example.md&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;plugins
&lt;ul&gt;
&lt;li&gt;markdown/
&lt;ul&gt;
&lt;li&gt;manifest.json&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;content.config.ts&lt;/strong&gt; # 集合 schema 权威定义&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;public/
&lt;ul&gt;
&lt;li&gt;favicon.svg&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;package.json
:::&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;终端输出写法&lt;/h3&gt;
&lt;p&gt;把 &lt;code&gt;tree&lt;/code&gt; 命令的输出直接粘进 &lt;code&gt;file-tree&lt;/code&gt; 围栏即可，Unicode 与 ASCII 分支符号都能解析。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dist
├── _astro/
│   ├── index.css
│   └── page.js
├── posts/
└── favicon.ico
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;8. 字段卡片 Field Cards&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;field-group&lt;/code&gt; 用来组织同一组 API 或组件参数；&lt;code&gt;field&lt;/code&gt; 也可以单独使用。&lt;/p&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field title
@type string
@required&lt;/p&gt;
&lt;p&gt;组件可见标题，会出现在页面标题与无障碍名称中，建议保持简短。
:::&lt;/p&gt;
&lt;p&gt;::: field disabled
@type boolean
@default &lt;code&gt;false&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;控件是否以禁用状态起始。
:::&lt;/p&gt;
&lt;p&gt;::: field locale
@type &lt;code&gt;&apos;zh-CN&apos; | &apos;en&apos; | &apos;ja-JP&apos;&lt;/code&gt;
@default &lt;code&gt;&apos;zh-CN&apos;&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;用于格式化日期、数字与无障碍标签的语言。
:::&lt;/p&gt;
&lt;p&gt;::: field legacyMode
@type boolean
@deprecated&lt;/p&gt;
&lt;p&gt;仅为向后兼容保留，新集成请改用 &lt;code&gt;compatibility&lt;/code&gt;。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;p&gt;单独使用一个字段：&lt;/p&gt;
&lt;p&gt;::: field format
@type &lt;code&gt;&apos;short&apos; | &apos;long&apos;&lt;/code&gt;
@default &lt;code&gt;&apos;short&apos;&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;控制结果的输出格式。
:::&lt;/p&gt;
&lt;h2&gt;9. 马克笔高亮 Marker&lt;/h2&gt;
&lt;p&gt;默认使用主题主色：==读者应该记住的那一个结论==。&lt;/p&gt;
&lt;p&gt;标记内部可以嵌套行内 Markdown：==嵌套 &lt;strong&gt;粗体强调&lt;/strong&gt;==。&lt;/p&gt;
&lt;p&gt;语义变体一共五种：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;==primary 连接当前主题=={.primary}&lt;/li&gt;
&lt;li&gt;==secondary 保持安静的次级区分=={.secondary}&lt;/li&gt;
&lt;li&gt;==tertiary 单独的编辑信号=={.tertiary}&lt;/li&gt;
&lt;li&gt;==error 需要修正的条件=={.error}&lt;/li&gt;
&lt;li&gt;==tip 实用建议=={.tip}&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;10. 缩写释义 Abbreviation&lt;/h2&gt;
&lt;p&gt;SSR 优先的输出让首屏文档在 JavaScript 执行前就可见；衡量阅读体验时，LCP 与 CLS 能说明首屏内容是否够快、够稳定。&lt;/p&gt;
&lt;p&gt;缩写也可以出现在 &lt;strong&gt;SSR&lt;/strong&gt; 这类强调文本旁边，但 &lt;code&gt;SSR&lt;/code&gt; 这种行内代码与 &lt;a href=&quot;https://web.dev/articles/lcp&quot;&gt;LCP 说明&lt;/a&gt; 这类链接不会被改写。&lt;/p&gt;
&lt;h2&gt;11. 内容标注 Content Annotation&lt;/h2&gt;
&lt;p&gt;Astro 会提前渲染页面的大部分内容，只在需要交互时水合&lt;strong&gt;交互孤岛&lt;/strong&gt; &lt;a href=&quot;**%E4%BB%80%E4%B9%88%E6%98%AF%E5%AD%A4%E5%B2%9B**&quot;&gt;+islands&lt;/a&gt;，因此默认页面足够轻。&lt;/p&gt;
&lt;p&gt;孤岛是被静态 HTML 包围的交互组件。它让页面默认保持轻量，同时保留聚焦的交互能力。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;首句尽量自成一体。&lt;/li&gt;
&lt;li&gt;需要原始出处时再给链接。&lt;/li&gt;
&lt;li&gt;优先给出 &lt;code&gt;client:visible&lt;/code&gt; 这样的具体示例。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;See the &lt;a href=&quot;https://docs.astro.build/en/concepts/islands/&quot;&gt;Astro islands documentation&lt;/a&gt; for the full model.&lt;/p&gt;
&lt;p&gt;同一个标签可以对应多条说明 &lt;a href=&quot;%E5%85%88%E7%BB%99%E4%BC%9A%E6%94%B9%E5%8F%98%E8%AF%BB%E8%80%85%E4%B8%8B%E4%B8%80%E6%AD%A5%E5%8A%A8%E4%BD%9C%E7%9A%84%E7%BB%93%E8%AE%BA%E3%80%82&quot;&gt;+review&lt;/a&gt;：&lt;/p&gt;
&lt;p&gt;未定义的引用 &lt;code&gt;[+missing]&lt;/code&gt; 会保持普通文本，不会生成空控件。&lt;/p&gt;
&lt;h2&gt;12. 行内剧透 Spoiler&lt;/h2&gt;
&lt;p&gt;答案是 :spoiler[&lt;strong&gt;42&lt;/strong&gt;]，这句话本身仍是普通 Markdown。&lt;/p&gt;
&lt;p&gt;剧透内容可以包含 &lt;code&gt;行内代码&lt;/code&gt;，也可以包含 :spoiler[较长的一段带 &lt;strong&gt;强调&lt;/strong&gt; 的细节]。&lt;/p&gt;
&lt;h2&gt;13. 数学公式 Math&lt;/h2&gt;
&lt;p&gt;行内公式：质能方程 $E = mc^2$，以及欧拉恒等式 $e^{i\pi} + 1 = 0$。&lt;/p&gt;
&lt;p&gt;块级公式：&lt;/p&gt;
&lt;p&gt;$$
\int_{-\infty}^{\infty} e^{-x^2} , \mathrm{d}x = \sqrt{\pi}
$$&lt;/p&gt;
&lt;h2&gt;14. Mermaid 图&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;flowchart LR
	accTitle: Markdown 渲染管线
	accDescr: Markdown 源文件经 remark/rehype 管线转换为语义化 HTML，再按需增强为跟随主题的图表。
	A[Markdown 源文件] --&amp;gt; B[remark / rehype 管线]
	B --&amp;gt; C[语义化 HTML]
	C --&amp;gt; D[跟随主题的图表]
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;15. 图片画廊与图片尺寸&lt;/h2&gt;
&lt;h3&gt;画廊容器&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;columns&lt;/code&gt; 取 1–6，&lt;code&gt;aspect&lt;/code&gt; 为宽高比，&lt;code&gt;fit&lt;/code&gt; 取 &lt;code&gt;cover&lt;/code&gt; 或 &lt;code&gt;contain&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;:::grid{columns=&quot;3&quot; aspect=&quot;16/9&quot; fit=&quot;cover&quot;}
&lt;img src=&quot;/images/albums/AcgExample/01.webp&quot; alt=&quot;画廊示例一&quot; /&gt;
&lt;img src=&quot;/images/albums/AcgExample/02.webp&quot; alt=&quot;画廊示例二&quot; /&gt;
&lt;img src=&quot;/images/albums/AcgExample/03.webp&quot; alt=&quot;画廊示例三&quot; /&gt;
:::&lt;/p&gt;
&lt;p&gt;:::grid{columns=&quot;2&quot; aspect=&quot;1/1&quot; fit=&quot;contain&quot;}
&lt;img src=&quot;/images/albums/AcgExample/04.webp&quot; alt=&quot;画廊示例四&quot; /&gt;
&lt;img src=&quot;/images/albums/AcgExample/05.webp&quot; alt=&quot;画廊示例五&quot; /&gt;
:::&lt;/p&gt;
&lt;h3&gt;宽度令牌与图注&lt;/h3&gt;
&lt;p&gt;独立图片的 alt 里可以带 &lt;code&gt;w-N%&lt;/code&gt; 宽度令牌（1–100），Markdown title 会渲染为居中图注。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/albums/AcgExample/07.webp&quot; alt=&quot;带宽度与图注的示例 w-50%&quot; title=&quot;半宽图片并带图注&quot; /&gt;&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/albums/AcgExample/08.webp&quot; alt=&quot;只有图注的示例&quot; title=&quot;没有宽度令牌时的图注&quot; /&gt;&lt;/p&gt;
&lt;p&gt;越界或非法令牌会保留在 alt 原文中，不会静默丢弃。&lt;/p&gt;
&lt;h2&gt;16. 文件包含 Include&lt;/h2&gt;
&lt;p&gt;按 region 片段包含：&lt;/p&gt;
&lt;p&gt;&amp;lt;!-- @include: src/content/snippets/include-example.md#public-api --&amp;gt;&lt;/p&gt;
&lt;p&gt;整文件包含与行范围包含的写法如下（这里仅作展示，不重复展开）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;!-- @include: src/content/snippets/include-example.md --&amp;gt;
&amp;lt;!-- @include: src/content/snippets/include-example.md{1-4} --&amp;gt;
&amp;lt;!-- @include: src/content/snippets/include-example.md{5-} --&amp;gt;
&amp;lt;!-- @include: src/content/snippets/include-example.md{-4} --&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;围栏内的 include 注释保持字面量，不会被展开。这里显式写上 &lt;code&gt;frame=&quot;none&quot;&lt;/code&gt;：Expressive Code 默认会从代码块前 4 行里挑一条「路径形态的注释」当作文件名标题，并把那一行整行删掉；这四种写法里不带范围的 &lt;code&gt;&amp;lt;!-- @include: ... --&amp;gt;&lt;/code&gt; 正好会被选中，只有加上 &lt;code&gt;frame=&quot;none&quot;&lt;/code&gt; 才会原样保留（该元数据的取值见 §20）。&lt;/p&gt;
&lt;h2&gt;17. 音频 Audio Reader&lt;/h2&gt;
&lt;p&gt;扬声器按钮在点击之前不会加载音频：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Ciallo&lt;/strong&gt; :audio-reader[Ciallo！！]{src=&quot;/assets/audio/Ciallo.wav&quot;}&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ehe&lt;/strong&gt; :audio-reader[A joking sense]{src=&quot;/assets/audio/Ehe.wav&quot;}&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Zako&lt;/strong&gt; :audio-reader[雑魚じゃん、雑魚雑魚]{src=&quot;/assets/audio/Zako.wav&quot;}&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code&gt;src&lt;/code&gt; 必须是站内根路径或显式 HTTPS 地址，指令标签不能为空。&lt;/p&gt;
&lt;h2&gt;18. 视频嵌入&lt;/h2&gt;
&lt;p&gt;下面四个指令都省略了 &lt;code&gt;preload&lt;/code&gt;，因此首屏只输出标题、播放按钮与回退链接，第三方播放器在点击后才加载。&lt;/p&gt;
&lt;h3&gt;YouTube&lt;/h3&gt;
&lt;p&gt;::youtube{id=&quot;5gIf0_xpFPI&quot; title=&quot;YouTube video&quot;}&lt;/p&gt;
&lt;h3&gt;Bilibili&lt;/h3&gt;
&lt;p&gt;::bilibili{bvid=&quot;BV1fK4y1s7Qf&quot; title=&quot;Bilibili video&quot; p=1}&lt;/p&gt;
&lt;h3&gt;AcFun&lt;/h3&gt;
&lt;p&gt;::acfun{acid=&quot;ac48649632&quot; title=&quot;AcFun video&quot;}&lt;/p&gt;
&lt;h3&gt;ArtPlayer&lt;/h3&gt;
&lt;p&gt;::artplayer{src=&quot;https://www.pexels.com/download/video/38538991/&quot; title=&quot;Sintel trailer&quot;}&lt;/p&gt;
&lt;h2&gt;19. GitHub 仓库卡片&lt;/h2&gt;
&lt;p&gt;::github{repo=&quot;all-thoughts-are-broken/blog&quot;}&lt;/p&gt;
&lt;p&gt;卡片信息在浏览器端从 GitHub API 拉取，因此它是本页唯一的强制外部请求。&lt;/p&gt;
&lt;h2&gt;20. Expressive Code 元数据&lt;/h2&gt;
&lt;h3&gt;标题、行号与行标记&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;export const app = true;

export const added = true;

export const legacy = true;

export const removed = true;

function collapsed() {
	return &quot;折叠区域&quot;;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;文本标记与正则&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;const island = &quot;client:visible&quot;;
const hydrate = false;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;const useStore = () =&amp;gt; {};
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;终端与代码框架&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd build
npx.cmd astro check
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;// frame=&quot;none&quot; 去除外框，startLineNumber 改变起始行号，wrap 允许长行换行
export const value = &quot;很长的行会在允许换行时折行显示&quot;;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;21. 语法清单核对&lt;/h2&gt;
&lt;p&gt;以上小节覆盖了 &lt;code&gt;src/plugins/markdown/manifest.json&lt;/code&gt; 登记的全部自定义语法。核对清单：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;#&lt;/th&gt;
&lt;th&gt;语法&lt;/th&gt;
&lt;th&gt;本文对应小节&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;&lt;code&gt;abbreviation&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;10&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;&lt;code&gt;acfun&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;18&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;&lt;code&gt;admonition&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;&lt;code&gt;artplayer&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;18&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;&lt;code&gt;audio-reader&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;17&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;&lt;code&gt;bilibili&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;18&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;&lt;code&gt;code-tree&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;td&gt;&lt;code&gt;collapse-panels&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;9&lt;/td&gt;
&lt;td&gt;&lt;code&gt;content-annotation&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;11&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10&lt;/td&gt;
&lt;td&gt;&lt;code&gt;expressive-code&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;20&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;11&lt;/td&gt;
&lt;td&gt;&lt;code&gt;fields&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;12&lt;/td&gt;
&lt;td&gt;&lt;code&gt;file-tree&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;13&lt;/td&gt;
&lt;td&gt;&lt;code&gt;github-card&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;19&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;14&lt;/td&gt;
&lt;td&gt;&lt;code&gt;image-grid&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;15&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;15&lt;/td&gt;
&lt;td&gt;&lt;code&gt;image-presentation&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;15&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;16&lt;/td&gt;
&lt;td&gt;&lt;code&gt;include&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;16&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;17&lt;/td&gt;
&lt;td&gt;&lt;code&gt;marker&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;9&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;18&lt;/td&gt;
&lt;td&gt;&lt;code&gt;math&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;13&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;19&lt;/td&gt;
&lt;td&gt;&lt;code&gt;mermaid&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;14&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;20&lt;/td&gt;
&lt;td&gt;&lt;code&gt;option-groups&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;21&lt;/td&gt;
&lt;td&gt;&lt;code&gt;spoiler&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;12&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;22&lt;/td&gt;
&lt;td&gt;&lt;code&gt;steps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;23&lt;/td&gt;
&lt;td&gt;&lt;code&gt;youtube&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;18&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;若某项未生效，请先确认对应实现是否仍注册在 &lt;code&gt;src/utils/markdown-processor.mjs&lt;/code&gt;，再检查 &lt;code&gt;pnpm.cmd check:markdown-manifest&lt;/code&gt; 与样式包登记。&lt;/p&gt;
</content:encoded></item></channel></rss>