本文是站点的语法验收页:每一节都在正文里真实使用一种语法,而不是把语法写进代码块里当文档。哪一项渲染不对,直接定位到对应小节即可。
1. 基础 Markdown 与 GFM
普通段落支持 斜体、粗体、粗斜体、删除线、行内代码,以及指向 Astro 官方文档 的链接和自动链接 https://astro.build/。
列表
- 无序列表项
- 第二项
- 嵌套子项
- 第三项
- 有序列表项
- 第二项
- 第三项
任务列表
- 已完成的事项
- 待办事项
引用与分隔线
引用可以跨段。
引用内部的 Markdown 依然生效。
表格
| 语法 | 入口类型 | 运行时成本 |
|---|---|---|
admonition | container | 原生,无 JS |
mermaid | fence | 按需加载客户端模块 |
math | inline-extension | 构建期生成,无 JS |
行内代码与围栏
反引号里的内容保持字面量:==这不是高亮==、:spoiler[这不是剧透]、[+也不是标注]。
2. 提示容器 Admonition
三种写法等价:带方括号标题、带空格标题、以及 GitHub Alert 引用语法。
折叠详情
details 使用原生 <details>,无 hydration、无客户端模块、无网络请求。
3. 折叠面板 Collapse Panels
独立开合
每项默认独立开合。标题前加 :+ 表示初始展开,:- 表示初始收起。
依赖要求
使用 Node.js 22 或更新版本,并在安装依赖前启用 Corepack。
安装依赖
在仓库根目录执行:
pnpm.cmd install运行校验
pnpm.cmd check:manifestnpx.cmd astro check
手风琴模式
加 accordion 后同一组内只保留一个展开项;expand 让首个面板默认展开。
这个面板为什么默认展开?
因为容器声明了 expand,且没有任何项带 :+ 标记。
标题里能有 Markdown 吗?
可以。标题支持 强调 与 代码,面板正文支持完整块级 Markdown。
窄屏表现如何?
内边距收窄、长文本换行,内嵌代码保持自己的横向滚动区域。
4. 选项组 Option Groups
同一个 #id 的多个选项组会跨页同步,选择结果也会被记住。
使用 npm 安装:
npm install astro使用 pnpm 安装:
pnpm.cmd add astro使用 Bun 安装:
bun add astro下面这组共用 package-manager,选择上面任一选项会同步切换这里。
npm run devpnpm.cmd devbun run dev5. 步骤流 Steps
属性标题
容器内必须恰好包含一个有序列表,每个顶层列表项就是一个步骤。
本地验收流程
准备环境
克隆仓库并安装依赖。
Terminal window pnpm.cmd install运行诊断
确认 Astro 诊断与清单校验全部通过。
Terminal window npx.cmd astro checkpnpm.cmd check:manifest构建产物
生成静态站点与搜索索引。
Terminal window pnpm.cmd build
方括号标题
快速开始
- 安装依赖
- 启动开发服务器
6. 代码树 Code Tree
容器写法
每个围栏用 title="路径" 声明自己在树中的位置。
export function greet(name: string): string { return `Hello, ${name}`;}目录自动导入
指向仓库内目录即可在构建期扫描生成,无需手工复制文件内容。
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 也可以单独使用。
组件可见标题,会出现在页面标题与无障碍名称中,建议保持简短。
false控件是否以禁用状态起始。
'zh-CN'用于格式化日期、数字与无障碍标签的语言。
仅为向后兼容保留,新集成请改用 compatibility。
单独使用一个字段:
'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
行内公式:质能方程 ,以及欧拉恒等式 。
块级公式:
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
Bilibili
AcFun
ArtPlayer
19. GitHub 仓库卡片
卡片信息在浏览器端从 GitHub API 拉取,因此它是本页唯一的强制外部请求。
20. Expressive Code 元数据
标题、行号与行标记
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 buildnpx.cmd astro check// frame="none" 去除外框,startLineNumber 改变起始行号,wrap 允许长行换行export const value = "很长的行会在允许换行时折行显示";21. 语法清单核对
以上小节覆盖了 src/plugins/markdown/manifest.json 登记的全部自定义语法。核对清单:
| # | 语法 | 本文对应小节 |
|---|---|---|
| 1 | abbreviation | 10 |
| 2 | acfun | 18 |
| 3 | admonition | 2 |
| 4 | artplayer | 18 |
| 5 | audio-reader | 17 |
| 6 | bilibili | 18 |
| 7 | code-tree | 6 |
| 8 | collapse-panels | 3 |
| 9 | content-annotation | 11 |
| 10 | expressive-code | 20 |
| 11 | fields | 8 |
| 12 | file-tree | 7 |
| 13 | github-card | 19 |
| 14 | image-grid | 15 |
| 15 | image-presentation | 15 |
| 16 | include | 16 |
| 17 | marker | 9 |
| 18 | math | 13 |
| 19 | mermaid | 14 |
| 20 | option-groups | 4 |
| 21 | spoiler | 12 |
| 22 | steps | 5 |
| 23 | youtube | 18 |
若某项未生效,请先确认对应实现是否仍注册在 src/utils/markdown-processor.mjs,再检查 pnpm.cmd check:markdown-manifest 与样式包登记。
分享文章
生成精美分享图或复制链接,与更多人分享本文。
最后更新于 ,距今已过 0 天
部分内容可能已过时




