---
title: 写作语法
description: 正文 Markdown 扩展——马克笔高亮、隐秘文本、缩写词与内容注释。
---

CelestPlume 在原生 Markdown 之上提供一组写作语法，移植自 Shirone 主题的
Plume 兼容语法。全部在构建期渲染；客户端脚本仅增强悬停、轻点与点击交互。
所有语法在 `.md` 与 `.mdx` 中均可用，对中英文页面同时生效，且在围栏代码与
行内代码内部永不触发。

## 马克笔高亮

使用成对的双等号 `==` 包裹文字获得荧光笔式下划线高亮；大括号后缀选择语义色。

撰写文档时，使用 **马克笔高亮** 标记核心要点。变体：**次级强调**、
**需要修正的内容**、**辅助提示** 与 **三级强调**。
嵌套格式可以保留：**加粗 **与** `行内代码`**。

```markdown
撰写文档时，使用 ==马克笔高亮== 标记核心要点。
==次级强调=={.secondary}
==需要修正的内容=={.error}
```

<PropsTable
  labels={{ prop: '变体', type: '令牌', default: '默认' }}
  type={{
    primary: { type: "'--cpd-gold'", default: '是', description: '默认——Plumest 淡金主色。' },
    secondary: { type: "'--cpd-accent-foreground'", description: '次级强调。' },
    tertiary: { type: "'--cpd-info'", description: '三级强调。' },
    error: { type: "'--cpd-error'", description: '警告与需要修正的内容。' },
    tip: { type: "'--cpd-success'", description: '建议与辅助提示。' },
  }}
/>

说明：

- 渲染为原生 `<mark>` 元素——屏幕阅读器看到的是普通强调文本。
- 未知变体回退为 `primary`；转义 `\==文本==` 保持字面量。
- 打印时高亮退化为更细的不透明下划线。

## 隐秘文本

`文本` 把内容藏进不透明黑幕。读者悬停（桌面）、轻点（触屏）、
键盘聚焦即可显现；点击可保持展开。

大结局揭示 侦探就是幕后主使。格式化同样生效：**加粗** 与 `行内代码`。

````markdown
大结局揭示 :spoiler[侦探就是幕后主使]。
````

说明：

- 黑幕为不透明深色遮罩——与行内代码（浅底、边框、等宽字体）明确区分。
- 悬停与聚焦由纯 CSS 显形；点击切换 `aria-expanded` 保持展开。
- 元素是原生 `<button>`；打印时全部显形。

## 缩写词

每页声明一次 `*[术语]: 释义` 字典，正文中出现的词条自动渲染为点状下划线的
`<abbr>` 并带气泡提示。本页在下方实际声明了两个术语——它们在构建期被消费，
不出现在渲染结果里：

```markdown
*[SSR]: 服务端渲染
*[AST]: 抽象语法树
```

有了上面的定义，下面这段话演示实时匹配：SSR 优化首屏加载，AST 在此之前
完成转换——SSR 与 AST 在句子任何位置都会匹配。

说明：

- 气泡在悬停、键盘聚焦、触屏轻点时显示（再次轻点、点击别处或 `Esc` 关闭，
  `Enter` / 空格也可切换）。
- 无 JavaScript 时原生 `title` 提示仍然可用。
- 匹配按词边界、区分大小写、最长优先；行内代码、链接、图片、围栏内跳过。
  非法或重复定义以纯文本形式保留在正文里。

## 内容注释

在正文插入 `[^tag]` 引用，并在页面任意位置（段落下方或文末）定义。注释在
徽标锚定的浮层卡片中弹出。

Astro 的孤岛架构 [^islands] 让页面保持极速。渲染器也支持 [^directive] 语法
——同一标签重复定义会累积为有序列表。

[^islands]: 
    孤岛架构指由静态 HTML 包裹的独立交互组件区域，只有交互区域才加载
    JavaScript。

[^directive]: 
    行内引用由 remark-directive 解析，构建期映射为 HTML。

[^directive]: 
    内容型组件一律使用 MDX 组件（`<X />`）形态，不涉及容器语法。

行内定义同样可用：[^inline] 一行写完。

[^inline]: 这条定义与标签写在同一行。

````markdown
Astro 的孤岛架构 [+islands] 让页面保持极速。

[+islands]:
  孤岛架构指由静态 HTML 包裹的独立交互组件区域，只有交互区域才加载
  JavaScript。
````

说明：

- 零 JavaScript：徽标是原生 `<button>`，经声明式 `popovertarget` 关联浮层；
  定位使用 CSS Anchor Positioning，并带居中回退。
- 未定义的标签保持字面量——`[^unknown]` 原样渲染。行内代码、链接、图片、
  围栏内不替换。
- 定义块会从正文流中移除；打印时隐藏浮层、保留徽标。