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

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

export const added = true;

export const legacy = true;

export const removed = true;

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