Chronicler 页面插入（Page Inserts）：一处修改，全库复用的强大功能

Chronicler 是一款免费、完全离线的世界构建（worldbuilding）工具和本地 Wiki，专为小说作家、跑团 GM 和桌游创作者设计。它的**页面插入（Page Inserts）**功能可以把任意一个 Markdown 页面的内容直接嵌入到另一个页面中——只需写一次，就能在整库复用；修改一处，所有引用它的地方自动更新。无需云同步、无需注册账号，你的世界永远只存在你自己的设备上。

🧩 什么是 Chronicler 页面插入（Page Inserts）

页面插入的语法只有一个：

{{insert: 页面名称}}

在任意页面里写上这一行，Chronicler 的预览就会把「页面名称」对应页面的完整内容渲染出来，放进一个带标题栏的引用框中。它特别适合这类"会被反复引用"的内容：

• 🗺️导航框（navbox）：章节导航、地区索引
• ⚔️属性块（stat block）：怪物数值、武器卡牌
• 📜通用条目：魔法体系规则、货币换算表、组织简介

好处很直接：只写一份，到处引用。改规则时只改一个文件，全库立即生效——这就是"一处修改，全库复用"。

官方帮助文档中的功能说明见 HELP.md，语法解析规则在 renderer.rs。

🚀 3 步快速上手：如何写出第一个页面插入

第 1 步：建一个"素材页"

先新建一个专门存放可复用内容的页面，例如魔法规则.md，只写内容本身，不写多余说明。

第 2 步：在目标页面插入它

在你想引用的页面（比如某个角色页）中写入：

{{insert: 魔法规则}}

页面名匹配不区分大小写，写魔法规则或魔法规则.md都可以，Chronicler 会通过索引自动定位到正确文件（解析逻辑见 parser.rs）。

第 3 步：切到预览查看效果

保存后在预览面板中，内容会以带标题栏的插入框呈现，右上角的[hide]按钮可随时折叠/展开（点击处理逻辑在 actions.ts）。插入框的默认样式定义在 preview.css。

🎛️ 4 个常用属性：让插入框更合身

在{{insert: ...}}语法里用|追加属性即可：

组合使用也很简单：

{{insert: 大战争 | title="大战争概要" | centered | hidden}} {{insert: 附魔匕首 | borderless}}

属性解析的具体实现位于 renderer.rs 的 process_single_insert 函数。

🔄 为什么能"一处修改，全库复用"？

页面插入不是复制粘贴，而是渲染时的动态嵌入（transclusion）。当你打开某页预览时，渲染器会：

1. 用索引找到被插入页面并读取其内容；
2. 自动剥离 YAML frontmatter（信息框元数据不会出现在插入框里）；
3. 递归渲染正文——被插入的页面里如果还有{{insert: ...}}，会继续展开。

配套的两个"省心机制"：

• 重命名自动跟随：当你重命名页面时，全库所有[[wikilinks]]和{{insert: ...}}引用都会被自动改写，属性参数（如title、hidden）原样保留，实现见 writer.rs。
• 循环引用保护：如果 A 插入 B、B 又插入 A，Chronicler 会在渲染栈中检测到并返回CircularInsert错误（error.rs），而不是无限递归卡死。

💡 实用技巧与常见问题

• 提示：插入框标题默认取被插入文件的文件名，起好素材页的文件名，插入效果会更整洁。
• 提示：hidden属性非常适合"剧透折叠"场景——配合||spoiler||语法可以做到双层隐藏。
• Insert not found：预览出现该报错框，通常是页面名拼写错误，或目标页面刚被删除，检查文件名即可。
• Could not read insert：文件存在但读取失败，检查文件权限或是否被外部程序占用。

📚 相关文档与源码路径

页面插入是 Chronicler 把"本地 Wiki 化写作"做到极致的一小块拼图：素材只写一次，链接自动维护，样式随主题走。对管理大型世界观的作家和 GM 来说，这是提升复用效率的必备技巧。