AsciiDoc 演示 // 技术

一篇 .adoc 文章的完整演示 —— 章节、列表、代码块、表格、提示框、交叉引用，渲染后与 Markdown 文章共用同一套 TUI 样式。

写作方式

在 src/content/posts/ 下放 .adoc 文件即可，和 .md 完全平权：文件名决定 URL （本篇是 asciidoc-demo.adoc，对应 /posts/asciidoc-demo），frontmatter 与 Markdown 文章共用同一套字段，目录、侧栏 Archive、CLI 的 posts 命令都会自动收录。

Note	标题来自 frontmatter。正文开头的 `= 标题` 文档头不会重复渲染成 h1，但如果你没写 frontmatter 的 `title`，它会作为兜底被采用。 `== 小节` 从二级标题开始，所以它们会被收进目录（左右两处目录都是同一份标题清单）。

frontmatter 字段

字段说明

字段	说明
`title`	标题，必填
`date`	日期，`YYYY-MM-DD`，必填
`category`	分类，必须是侧栏分类的 slug，必填
`tags`	标签数组，可省略
`summary`	摘要，可省略
`draft`	`true` 则不进构建，可省略
`pinned`	`true` 则在该分类内置顶，可省略

title

标题，必填

date

日期，YYYY-MM-DD，必填

category

分类，必须是侧栏分类的 slug，必填

tags

标签数组，可省略

summary

摘要，可省略

draft

true 则不进构建，可省略

pinned

true 则在该分类内置顶，可省略

文本标记

段落里的粗体、斜体、等宽、^上标、_下标都能用。行内链接写成 Asciidoctor 官网；裸 URL 也会自动变成链接。

列表语法与 Markdown 不同，但样式是同一条 CSS：

无序列表项
- 嵌套一项
另一项
1. 有序列表第一项
2. 第二项
  
  术语
  
  描述列表，AsciiDoc 特有的写法
  
  另一个术语
  
  描述文本

代码与引用

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

Note	代码块的语法高亮在 AsciiDoc 这一侧不启用 —— 本站 `.post-body pre` 的样式统一接管背景与边框，所以两种格式的代码块观感一致（Markdown 那侧因为走 Shiki，token 会带颜色）。

A language that doesn’t affect the way you think about programming is not worth knowing.

— Alan J. Perlis
Epigrams in Programming

提示框

Warning

WARNING / NOTE / TIP / IMPORTANT / CAUTION 都是平台写法：[WARNING] 起一行，正文包在 ==== 之间，就能得到带标题栏的提示块。

Tip	单行的 TIP 也可以直接用 `TIP: 文字` 写。

交叉引用

带显式锚点的小节

把小节想要的锚点写在标题的上方一行，就能固定它的 id（放在代码块里展示，因为正文字面写出锚点语法会被 Asciidoctor 当成第二个锚点定义）：

[[my-anchor]]
=== 小节标题

本次演示的小节锚点是 demo-cross-ref，所以在别处写带显式锚点的小节就能跳到它，链接文字会自动取小节标题。至于没写锚点的小节，id 由标题生成：英文按连字符分词，中文标题本身就是锚点。

收尾

上面这些结构都由 Asciidoctor 转成 HTML，再由文章路由交给同一套 .post-body 样式，所以新增 AsciiDoc 排版能力（例如脚注、旁注、包含指令）时，只需要在 src/pages/posts/[…slug].astro 的样式区补规则，不必碰内容层的代码。