零鹊文档 · AI 编写语法规范（Lingque Docs Authoring Spec）

受众：任意 AI 助手、代码 Agent、自动化脚本。
用途：在零鹊文档后台创建或修改页面时，必须遵守本文件中的语法与边界。
存储位置：页面 标题 字段 + 正文 字段（Markdown 字符串）。正文经

renderPageMarkdown()

渲染；标题经

renderTitle()

渲染（仅列表/侧栏/上下篇，正文页不显示页面标题）。

0. 元信息（给 AI 的快速约束）

1. 页面标题字段（

pages.title

）

标题是纯字符串，可混用徽章短代码与普通文字。渲染位置：侧栏、文档中心卡片标题、上一篇/下一篇、浏览器

<title>

1.1 内置/可配置徽章（成对标签）

语法（

tag

hot

new

update

top

vip

[tag]内文[/tag]

规则：

1. 开闭标签名必须一致（大小写可不同，会规范为小写 class）。
2. 内文 ≤4 个字符且无空格：整段文字显示在徽章内（如

   [hot]热[/hot]

   ）。
3. 内文较长：仅显示配置中的短

   label

   （如「热」）+ 空格 + 剩余标题文字。
   例：标题

   [hot]1-零鹊文档 编写指南[/hot]

   → 徽章「热」+

   1-零鹊文档 编写指南

   。
4. 同一标题可多个徽章+文字混排：

   [new]新[/new] [hot]指南[/hot]

   （按书写顺序渲染）。

示例（写入标题字段）：

[hot]零鹊编写指南[/hot]
[top]置顶[/top] 服务器规则
[vip]荐[/vip]

1.2 标题颜色

[color=CSS颜色]文字[/color]

• CSS颜色

  ：

  red

  、

  #ff0000

  、

  #f00

  、

  rgba(0,0,0,0.5)

  等（非法值会回退为安全默认色）。
• 可与徽章混用：

  [color=#007aff]蓝色标题[/color]

  。

1.3 标题中应避免

• [html]…[/html]

  、

  [css]…[/css]

  ：在

  <title>

  中会被剥离，前台标题区也不显示大标题。
• 未闭合的

  [tag]

  ：原样显示为普通文本。

1.4 站点级徽章配置（AI 需知晓，非正文语法）

管理员在 站点设置 → 标题徽章 维护 JSON：

{
  "hot": { "label": "热", "bg": "rgba(255,59,48,0.15)", "color": "#ff3b30" },
  "vip": { "label": "VIP", "bg": "rgba(124,58,237,0.12)", "color": "#7c3aed" }
}

键名 = 标题里

[键名]…[/键名]

a-z0-9_-

2. 正文 Markdown（标准语法）

正文写入 content 字段。支持常规 Markdown（由 Parsedown 解析）。

2.1 标题（H1–H6）

# H1
## H2
### H3

• H1–H3 会生成右侧 TOC 目录 与标题锚点（悬停可复制章节链接）。
• 正文页不在文首重复显示

  pages.title

  ；文档结构请用正文内

  #

  标题。

2.2 强调与行内

**粗体**
*斜体*
~~删除线~~
`行内代码`

2.3 列表

- 无序
- 项

1. 有序
2. 项

2.4 引用

> 引用一行
> > 嵌套引用

2.5 链接与图片

[链接文字](https://example.com/path)
![图片说明](https://example.com/image.png)

• 图片：懒加载、可点击全屏；说明文字作图注。

2.6 表格

| 列1 | 列2 |
| --- | --- |
| a | b |

前台表格外层自动包

table-scroll

2.7 围栏代码块

```java
public class Main {}
```

• 围栏行可写语言：java php python javascript bash sql json html css yaml xml 等。
• 前台：语言标签 + 复制按钮；<p> 包裹 <pre> 会被拆开修复。

2.8 分割线

---

3. 正文增强短代码（零鹊专有）

处理顺序（概念上）：标题锚点 → 保护行内代码 → [html] [css] [php] [embed] → Markdown → 表格包裹等。

3.1 [html]…[/html]

注入 原始 HTML（不做 Markdown 转义）。

[html]
<div class="notice">
  <strong>提示</strong>：请遵守服务器规则。
</div>
[/html]

AI 注意：

• 与 [css] 搭配时，优先用 class，样式写在 [css] 块。
• 可用主题 CSS 变量：var(--bg-card) var(--text-main) var(--accent) var(--border) var(--bg-glass) var(--radius-md) var(--shadow) 等（与前台 style.css 一致）。

3.2 [css]…[/css]

注入页面级 <style> 块。

[css]
.doc-notice {
  border-left: 4px solid var(--accent);
  padding: 1rem;
  background: var(--bg-card);
}
[/css]

3.3 [embed …]（自闭合属性式，无 [/embed]）

[embed url="https://example.com"]
[embed url="https://example.com" width="100%" height="500px"]

输出为带 sandbox 的 <iframe>（allow-scripts allow-same-origin allow-popups allow-forms）。

3.4 [php]…[/php]（仅前台执行）

[php]
$db = Database::getInstance();
$n = $db->query("SELECT COUNT(*) FROM pages WHERE is_published = 1")->fetchColumn();
echo '<p>已发布文档数：' . (int)$n . '</p>';
[/php]

允许使用的 API（白名单思路，实际为同项目函数）：

禁止：$_GET/$_POST 直接输出、文件删除、外链请求、任意 eval 字符串。

标签内可写 <?php 也可不写，系统会剥离后再 eval。

4. 文档中心卡片主题（非正文语法）

每篇页面在后台可选 卡片主题（仅存 pages.card_style JSON），影响 docs.php 列表卡片外观，不影响正文排版。

4.1 站点预设 JSON（站点设置 → 文档卡片主题）

{
  "default": {
    "label": "默认",
    "variant": "default",
    "accent": "",
    "bg": "",
    "border": ""
  },
  "featured": {
    "label": "强调",
    "variant": "featured",
    "accent": "#007aff",
    "bg": "",
    "border": ""
  },
  "vip": {
    "label": "VIP",
    "variant": "featured",
    "accent": "#7c3aed",
    "bg": "rgba(124,58,237,0.08)",
    "border": ""
  }
}

4.2 单页覆盖（pages.card_style）

{ "theme": "featured", "accent": "#ff0000", "excerpt_len": 120 }

兼容旧数据：仅含 "variant":"outline" 时按 theme=outline 解析。

5. 前台行为摘要（AI 写文时预期效果）

6. 完整示例（AI 可直接拆成 title + content）

title：

[hot]零鹊文档 AI 语法说明[/hot]

content：

# 概述

本文说明零鹊文档支持的写法。

## 标准 Markdown

支持 **粗体**、列表与表格。

| 类型 | 支持 |
| --- | --- |
| Markdown | 是 |
| 短代码 | 是 |

## 提示块（HTML + CSS）

[css]
.ai-tip {
  padding: 1rem;
  border-radius: 8px;
  background: var(--accent-bg);
  border: 1px solid var(--border);
}
[/css]

[html]
<div class="ai-tip">
  <strong>提示</strong>：增强语法请勿输出未转义的用户输入。
</div>
[/html]

## 嵌入示例

[embed url="https://www.example.com" height="400px"]

## 动态统计（慎用 PHP）

[php]
echo '<p>站点名称：' . htmlspecialchars(getSetting('site_name', '零鹊文档')) . '</p>';
[/php]

7. 语法速查（机器可读）

title_field:
  badge: "[{tag}]{inner}[/{tag}]"
  color: "[color={css_color}]{text}[/color]"
  tags_from: settings.title_badge_presets JSON keys
body_markdown:
  standard: [headings, bold, italic, strike, code_inline, code_fence, link, image, table, blockquote, list, hr]
  shortcodes:
    html: "[html]...[/html]"
    css: "[css]...[/css]"
    php: "[php]...[/php]"  # eval on frontend only
    embed: '[embed url="..." width="..." height="..."]'
card_theme:
  preset: settings.card_theme_presets JSON
  per_page: pages.card_style JSON { theme, accent?, excerpt_len? }
forbidden_in_php: [unsanitized user input, shell_exec, file unlink, remote fetch]
strip_from_excerpt: [html, css, php, embed blocks]

8. 相关文件（维护者）

版本：与仓库卡片主题/徽章自定义功能同步（2026-06）。若语法变更，请同时更新本文件与 `docs_guide.md