4901 字
25 分钟
Markdown 语法全量测试

本文是站点的语法验收页:每一节都在正文里真实使用一种语法,而不是把语法写进代码块里当文档。哪一项渲染不对,直接定位到对应小节即可。

1. 基础 Markdown 与 GFM#

普通段落支持 斜体、粗体、粗斜体、删除线、行内代码,以及指向 Astro 官方文档 的链接和自动链接 https://astro.build/。

列表#

  • 无序列表项
  • 第二项
    • 嵌套子项
  • 第三项
  1. 有序列表项
  2. 第二项
  3. 第三项

任务列表#

  • 已完成的事项
  • 待办事项

引用与分隔线#

引用可以跨段。

引用内部的 Markdown 依然生效。


表格#

语法入口类型运行时成本
admonitioncontainer原生,无 JS
mermaidfence按需加载客户端模块
mathinline-extension构建期生成,无 JS

行内代码与围栏#

反引号里的内容保持字面量:==这不是高亮==、:spoiler[这不是剧透]、[+也不是标注]。

2. 提示容器 Admonition#

三种写法等价:带方括号标题、带空格标题、以及 GitHub Alert 引用语法。

折叠详情

details 使用原生 <details>,无 hydration、无客户端模块、无网络请求。

3. 折叠面板 Collapse Panels#

独立开合#

每项默认独立开合。标题前加 :+ 表示初始展开,:- 表示初始收起。

依赖要求

使用 Node.js 22 或更新版本,并在安装依赖前启用 Corepack。

安装依赖

在仓库根目录执行:

Terminal window
pnpm.cmd install
运行校验
  • pnpm.cmd check:manifest
  • npx.cmd astro check

手风琴模式#

加 accordion 后同一组内只保留一个展开项;expand 让首个面板默认展开。

这个面板为什么默认展开?

因为容器声明了 expand,且没有任何项带 :+ 标记。

标题里能有 Markdown 吗?

可以。标题支持 强调 与 代码,面板正文支持完整块级 Markdown。

窄屏表现如何?

内边距收窄、长文本换行,内嵌代码保持自己的横向滚动区域。

4. 选项组 Option Groups#

同一个 #id 的多个选项组会跨页同步,选择结果也会被记住。

npm

使用 npm 安装:

Terminal window
npm install astro
pnpm

使用 pnpm 安装:

Terminal window
pnpm.cmd add astro
Bun

使用 Bun 安装:

Terminal window
bun add astro

下面这组共用 package-manager,选择上面任一选项会同步切换这里。

npm
Terminal window
npm run dev
pnpm
Terminal window
pnpm.cmd dev
Bun
Terminal window
bun run dev

5. 步骤流 Steps#

属性标题#

容器内必须恰好包含一个有序列表,每个顶层列表项就是一个步骤。

本地验收流程

  1. 准备环境

    克隆仓库并安装依赖。

    Terminal window
    pnpm.cmd install
  2. 运行诊断

    确认 Astro 诊断与清单校验全部通过。

    Terminal window
    npx.cmd astro check
    pnpm.cmd check:manifest
  3. 构建产物

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

    Terminal window
    pnpm.cmd build

方括号标题#

快速开始

  1. 安装依赖
  2. 启动开发服务器

6. 代码树 Code Tree#

容器写法#

每个围栏用 title="路径" 声明自己在树中的位置。

语法测试样例
src/greet.ts
export function greet(name: string): string {
return `Hello, ${name}`;
}

目录自动导入#

指向仓库内目录即可在构建期扫描生成,无需手工复制文件内容。

音乐工具模块
playlist.ts
import type { PlaybackMode } from "@/types/musicConfig";
export function nextTrackIndex(
currentIndex: number,
length: number,
mode: PlaybackMode,
random: () => number = Math.random,
): number {
if (length <= 0) return -1;
if (length === 1 || mode === "repeat-one") return Math.max(0, currentIndex);
if (mode !== "shuffle") return (Math.max(0, currentIndex) + 1) % length;
const offset = 1 + Math.floor(random() * (length - 1));
return (Math.max(0, currentIndex) + offset) % length;
}
export function previousTrackIndex(
currentIndex: number,
length: number,
mode: PlaybackMode,
random: () => number = Math.random,
): number {
if (length <= 0) return -1;
if (length === 1 || mode === "repeat-one") return Math.max(0, currentIndex);
if (mode === "shuffle") {
return nextTrackIndex(currentIndex, length, mode, random);
}
return (Math.max(0, currentIndex) - 1 + length) % length;
}

7. 文件树 File Tree#

嵌套列表写法#

目录以结尾斜杠标记为默认收起,++ / -- 标记新增与删除,# 之后是行内注释,**粗体** 用于强调关键文件。

站点内容结构
  • src
    • components
      • +SideBar.astro侧栏编排入口
      • -OldWidget.svelte已下线组件
    • content
      • posts
        • markdown-syntax-test.md
      • snippets
        • include-example.md
    • plugins
      • markdown
        • manifest.json
    • content.config.ts集合 schema 权威定义
  • public
    • favicon.svg
  • package.json

终端输出写法#

把 tree 命令的输出直接粘进 file-tree 围栏即可,Unicode 与 ASCII 分支符号都能解析。

构建产物
  • dist
    • _astro
      • index.css
      • page.js
    • posts
    • favicon.ico

8. 字段卡片 Field Cards#

field-group 用来组织同一组 API 或组件参数;field 也可以单独使用。

title必填string

组件可见标题,会出现在页面标题与无障碍名称中,建议保持简短。

disabled可选boolean
false

控件是否以禁用状态起始。

locale可选'zh-CN' | 'en' | 'ja-JP'
'zh-CN'

用于格式化日期、数字与无障碍标签的语言。

legacyMode已弃用boolean

仅为向后兼容保留,新集成请改用 compatibility。

单独使用一个字段:

format可选'short' | 'long'
'short'

控制结果的输出格式。

9. 马克笔高亮 Marker#

默认使用主题主色:读者应该记住的那一个结论。

标记内部可以嵌套行内 Markdown:嵌套 粗体强调。

语义变体一共五种:

  • primary 连接当前主题
  • secondary 保持安静的次级区分
  • tertiary 单独的编辑信号
  • error 需要修正的条件
  • tip 实用建议

10. 缩写释义 Abbreviation#

SSR 优先的输出让首屏文档在 JavaScript 执行前就可见;衡量阅读体验时,LCP 与 CLS 能说明首屏内容是否够快、够稳定。

缩写也可以出现在 SSR 这类强调文本旁边,但 SSR 这种行内代码与 LCP 说明 这类链接不会被改写。

11. 内容标注 Content Annotation#

Astro 会提前渲染页面的大部分内容,只在需要交互时水合交互孤岛 ,因此默认页面足够轻。

同一个标签可以对应多条说明 :

未定义的引用 [+missing] 会保持普通文本,不会生成空控件。

12. 行内剧透 Spoiler#

答案是 ,这句话本身仍是普通 Markdown。

剧透内容可以包含 行内代码,也可以包含 。

13. 数学公式 Math#

行内公式:质能方程 E=mc2E = mc^2,以及欧拉恒等式 eiπ+1=0e^{i\pi} + 1 = 0。

块级公式:

∫−∞∞e−x2 dx=π\int_{-\infty}^{\infty} e^{-x^2} \, \mathrm{d}x = \sqrt{\pi}

14. Mermaid 图#

flowchart LR
	accTitle: Markdown 渲染管线
	accDescr: Markdown 源文件经 remark/rehype 管线转换为语义化 HTML,再按需增强为跟随主题的图表。
	A[Markdown 源文件] --> B[remark / rehype 管线]
	B --> C[语义化 HTML]
	C --> D[跟随主题的图表]

15. 图片画廊与图片尺寸#

画廊容器#

columns 取 1–6,aspect 为宽高比,fit 取 cover 或 contain。

画廊示例一
画廊示例一
画廊示例二
画廊示例二
画廊示例三
画廊示例三
画廊示例四
画廊示例四
画廊示例五
画廊示例五

宽度令牌与图注#

独立图片的 alt 里可以带 w-N% 宽度令牌(1–100),Markdown title 会渲染为居中图注。

带宽度与图注的示例
半宽图片并带图注
只有图注的示例
没有宽度令牌时的图注

越界或非法令牌会保留在 alt 原文中,不会静默丢弃。

16. 文件包含 Include#

按 region 片段包含:

export function greet(name: string) {
return `Hello, ${name}`;
}

整文件包含与行范围包含的写法如下(这里仅作展示,不重复展开):

<!-- @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} -->

围栏内的 include 注释保持字面量,不会被展开。这里显式写上 frame="none":Expressive Code 默认会从代码块前 4 行里挑一条「路径形态的注释」当作文件名标题,并把那一行整行删掉;这四种写法里不带范围的 <!-- @include: ... --> 正好会被选中,只有加上 frame="none" 才会原样保留(该元数据的取值见 §20)。

17. 音频 Audio Reader#

扬声器按钮在点击之前不会加载音频:

  • Ciallo Ciallo!!
  • Ehe A joking sense
  • Zako 雑魚じゃん、雑魚雑魚

src 必须是站内根路径或显式 HTTPS 地址,指令标签不能为空。

18. 视频嵌入#

下面四个指令都省略了 preload,因此首屏只输出标题、播放按钮与回退链接,第三方播放器在点击后才加载。

YouTube#

YouTube videoYouTube

Bilibili#

Bilibili videoBilibili

AcFun#

AcFun videoAcFun

ArtPlayer#

Sintel trailerhttps://www.pexels.com/download/video/38538991/

19. GitHub 仓库卡片#

all-thoughts-are-brokenblog

卡片信息在浏览器端从 GitHub API 拉取,因此它是本页唯一的强制外部请求。

20. Expressive Code 元数据#

标题、行号与行标记#

app.js
export const app = true;
export const added = true;
export const legacy = true;
3 collapsed lines
export const removed = true;
function collapsed() {
return "折叠区域";
}

文本标记与正则#

const island = "client:visible";
const hydrate = false;
const useStore = () => {};

终端与代码框架#

构建与校验
pnpm.cmd build
npx.cmd astro check
// frame="none" 去除外框,startLineNumber 改变起始行号,wrap 允许长行换行
export const value = "很长的行会在允许换行时折行显示";

21. 语法清单核对#

以上小节覆盖了 src/plugins/markdown/manifest.json 登记的全部自定义语法。核对清单:

#语法本文对应小节
1abbreviation10
2acfun18
3admonition2
4artplayer18
5audio-reader17
6bilibili18
7code-tree6
8collapse-panels3
9content-annotation11
10expressive-code20
11fields8
12file-tree7
13github-card19
14image-grid15
15image-presentation15
16include16
17marker9
18math13
19mermaid14
20option-groups4
21spoiler12
22steps5
23youtube18

若某项未生效,请先确认对应实现是否仍注册在 src/utils/markdown-processor.mjs,再检查 pnpm.cmd check:markdown-manifest 与样式包登记。

Server-Side RenderingLargest Contentful PaintCumulative Layout ShiftServer-Side Rendering
Markdown 语法全量测试
https://blog.0x2d1.us.kg/posts/markdown-syntax-test/
作者
Shirone
发布于
2026-09-16
许可协议
CC BY-NC-SA 4.0

分享文章

生成精美分享图或复制链接,与更多人分享本文。