指南 · 架构

三分边界

用这套工具搭起来的文档/wiki 站由三部分拼成,每部分恰好只管一层。层与层之间的线不是审美偏好——每条线背后都压着一条硬约束,越界就会咬人。

三个仓 · 三个主人 · 一句口诀

§1三层,三个主人

• astro-inkbrush(引擎):一个极简 CMS——在浏览器里按块就地编辑、块级修订历史与回滚、评论、AI 问答/改写/翻译、收件箱导入。它还管着一件看上去不该归 CMS 的事:markdown 方言与内容守门。理由很硬:编辑器接受的语法与页面渲染的语法必须是同一套,否则「编辑器里存得好好的,页面上渲染坏了」只是时间问题。所以解析规则只在引擎里写一次,三处消费——站点渲染、CMS 保存校验、CI 检查。
• astro-inkstone(纸面,就是本包):共享的观感与管线层——两套语境下的两层设计 token、内容样式表 base.css 与书架样式 browse.css、组件库、siteMarkdown 管线预设、本园地赖以运转的分类与反向链接工具、Maple Mono CN 代码字体子集,还有渲染体检的两支探针。站点身份它不碰:品牌色、布局 chrome、路由与部署,都不关它的事。
• 站点(比如你正在读的这座园地):覆盖第一层 token,定下自己的身份色;自己写 Sidebar 与导航 chrome(本站的实现就是参考答案);内容怎么组织、路由长什么样、部署到哪里,都由它说了算。

一句口诀:引擎管编辑,纸面管观感,站点就是你。

§2边界为什么画在这里

每一刀背后,都有一条实打实的约束:

方言归引擎,因为检查器的插件集一旦和站点的不一样,比没有检查还糟——缺了数学插件的检查器会把公式花括号误读成 JSX 表达式,没开 GFM 的会对表格竖线放行。语法只写一次、三处共用,想走散也走散不了。

样式归纸面,因为几个站各自维护一份内容样式表时,一处对比度修复就得每站抄一遍——哪个站漏了,哪个站的小字就跌破 AA(WCAG 无障碍标准要求的对比度下限)。放进共享层,修一次,处处生效。

身份归站点,因为共享层一旦吸进某一个站的品牌色,其余每个站都得靠覆盖去和它对抗。两层 token 正是为此而设:站点只覆盖第一层原始色板(--p-*),语义层与组件层一行不改、整体跟着换色——见 设计 token。

§3导览机制归哪一层

你此刻正在用的导览,同样服从这套纪律。包出机制——createTaxonomy(kind/domain/tag 的解析、总览页的字段继承、语言镜像)、createBacklinks(反向链接索引),以及落地页上的笔记卡、分类行这类纯展示组件。站点出词汇与路由:这座园地的 kind 与 domain 定义在它自己的注册表文件里,/kind/…、/domain/…、/tag/… 页面就是普通的 Astro 页面,消费站照抄一份再改成自己的样子。同一套拆分,再上一层:机制在包,含义在站。

§4站点拿到什么

站在站点的角度,引入本包加引擎,换来的是:

• astro-inkstone/styles/tokens.css + base.css + browse.css:先 token,再阅读列,再书架——三行 @import 拿下整套观感;
• siteMarkdown(...):整条 markdown 管线一行接通,各开关的说明见 快速上手;
• astro-inkstone/components/ 下的组件,按路径按需导入;
• astro-inkstone/lib/ 下的分类工厂与反向链接构建器,绑到站点自己的注册表上;
• WIKI 模式下,引擎的完整 CMS(在本站跑 npm run wiki 就能试到);
• 五道检查:check-content、check-wikilinks、check-dist 随引擎分发,ui_probe、contrast_probe 随本包分发——见 五道检查。

这座园地每一页上的每一处渲染效果,都出自这套拆分——笔记即手册,手册即示范。