零鹊文档 编写指南

本系统使用增强版 Markdown 进行文档编写，除标准 Markdown 语法外，额外支持高度定制化的动态组件注入功能。

在后台「页面管理」或「新建页面」中，可直接使用以下语法编写图文并茂的文档。

1. 基础排版语法 (Markdown)

1.1 标题

使用

#

# 一级标题 (H1 - 大章节)
## 二级标题 (H2)
### 三级标题 (H3)

1.2 文本样式

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

1.3 列表

- 新手指南
- 进阶攻略
- 常见问题

1. 第一步：注册账号
2. 第二步：下载客户端
3. 第三步：连接服务器

1.4 引用

使用

>

> **重要提示**
> 请勿在主城区域恶意破坏方块，违者将被关入小黑屋。

支持引用嵌套：

> 一级引用
> > 二级引用（嵌套）

1.5 代码块

在编辑器里用围栏代码块：单独一行写三个英文反引号，下一行起写代码，结束再单独一行三个反引号。开头的反引号行可写语言名（如 java），前台会显示语言标签和复制按钮。

示例（以下为真实代码块渲染效果）：

public class Main {
    public static void main(String[] args) {
        System.out.println("Hello Minecraft!");
    }
}

源文件写法示意（在编辑器中按下面缩进内容输入即可，首尾各一行三个反引号，第一行反引号后写 java）：

```java
public class Main {
    public static void main(String[] args) {
        System.out.println("Hello Minecraft!");
    }
}
```

支持的语言标识：java、php、python、javascript、bash、sql、json、html、css、yaml、xml 等。未写语言时顶部显示 code。

行内代码用单个反引号包住标识符，例如用反引号包住 System.out.println() 这个方法名。

1.6 链接与图片

[点击访问官方网站](https://example.com)

![图片描述](https://example.com/image.jpg)

1.7 表格

| 物品名称 | 稀有度 | 用途 |
| --- | --- | --- |
| 钻石剑 | 稀有 | 近战武器 |
| 铁锭 | 普通 | 合成材料 |
| 附魔书 | 稀有 | 装备强化 |

1.8 分割线

---

1.9 任务列表

- [x] 已完成的事项
- [ ] 待完成的事项
- [ ] 另一个待办

2. 增强组件语法 (Shortcodes)

为弥补纯 Markdown 在复杂排版和组件交互上的不足，系统支持类似 BBCode 的闭合标签，可直接往文档中注入前端代码、CSS 样式或后端逻辑。

预览机制说明：
后台点击「预览」时，

[html]

和

[css]

会解析并在预览框内生效；

[php]

因安全限制仅高亮展示不执行，只有前台访问时才会真正运行；

[embed]

在预览和前台均可正常渲染。

2.1 注入自定义 HTML

[html]

需要实现纯 Markdown 无法完成的排版（并排卡片、投票按钮等）时使用。

[html]
<div style="border: 2px solid #0a84ff; padding: 15px; border-radius: 8px;">
    <h3>赞助渠道已开启</h3>
    <p>点击下方按钮前往充值页面获取 VIP 权限！</p>
    <a href="/vip" style="display:inline-block;background:#0a84ff;color:white;padding:8px 16px;border-radius:4px;text-decoration:none;">前往赞助</a>
</div>
[/html]

2.2 注入页面级 CSS

[css]

搭配

[html]

style

<style>

[css]
.my-card {
    background: var(--bg-glass);
    padding: 20px;
    border-radius: 12px;
    border: 1px solid var(--accent);
    transition: transform 0.2s;
}
.my-card:hover {
    transform: translateY(-5px);
}
[/css]

[html]
<div class="my-card">
    <h4>新赛季你最期待的玩法？</h4>
    <button>RPG 副本</button>
    <button>自动化工业</button>
</div>
[/html]

可使用系统内置的 CSS 变量保持主题一致性：

2.3 嵌入外部网页/视频

[embed]

在文档中嵌入 Bilibili 视频、YouTube 视频或其他外部网站，无需手写 iframe 代码。

默认尺寸（100% 宽度，500px 高度）：

[embed url="https://example.com"]

自定义宽高：

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

嵌入 B站视频示例：

[embed url="//player.bilibili.com/player.html?isOutside=true&aid=1128795048&bvid=BV1D1421r7Y8&cid=1630120150&p=1" width="100%" height="600px"]

嵌入 Google 地图示例：

[embed url="https://www.google.com/maps/embed?pb=!1m18" width="100%" height="450px"]

安全说明： 所有嵌入的 iframe 均启用

sandbox

沙箱模式，限制脚本权限，防止外部网站影响本站安全。

2.4 注入动态 PHP 逻辑

[php]

允许在文档中嵌入后端代码，动态展示数据库数据或根据条件渲染不同内容。

安全警告： 此功能在前台执行真正的

eval()

，绝对不要在标签内输出未经验证的用户输入。

[php]
$db = Database::getInstance();
$adminCount = $db->query("SELECT COUNT(*) FROM admin")->fetchColumn();

echo "<div style='background:rgba(16,185,129,0.1);color:#10b981;padding:10px;border-radius:8px;text-align:center;font-weight:bold;'>";
echo "当前系统共有 {$adminCount} 名管理员在线守护服务器！";
echo "</div>";
[/php]

可在

[php]

3. 前台渲染特性

3.1 自动目录 (TOC)

使用 H1~H3 标题时，页面右侧会自动生成跟随滚动高亮的 TOC 目录，无需手动编写。

3.2 标题锚点链接

所有 H1~H3 标题自动生成锚点。鼠标悬停标题时会出现链接图标，点击可获取该标题的直达 URL，方便在聊天中分享具体章节。

3.3 代码块增强

代码块顶部常驻显示语言标签和一键复制按钮，滚动条默认淡化，悬停时才显现。

3.4 上下篇导航

页面底部自动生成同分类下的上一篇/下一篇导航，方便读者连续阅读。

4. 书写与排版建议

1. 善用目录： 使用标准

   #

   标题，前台自动生成 TOC。
2. 段落间距： 段落之间保持一个空行，确保舒适的行距。
3. 合理分类： 在「页面属性」中为文档选择合适的分类，方便玩家按主题查找。
4. 排序权重： 通过「页面属性」中的排序数值控制同分类下页面的显示顺序，数字越小越靠前。也可在「分类管理」中通过拖拽调整顺序。
5. 增强语法安全：

   [html]

   /

   [css]

   /

   [php]

   /

   [embed]

   在文档列表摘要中会被自动过滤，不会破坏卡片排版，放心使用。
6. 草稿机制： 编辑中的文档可关闭「已发布」开关保存为草稿，仅管理员可在前台通过直接链接访问，普通玩家不可见。

5. 语法速查表