架构图与系统流向：Maplen 是如何运转的
从 4N 正交体系到静态优先流水线，用 Mermaid 图表全景解析我为 Maplen 搭建的底层逻辑
专栏 · Maplen在写技术实践手记时，我经常需要表达复杂的系统结构、通信协议和业务流向。
但我非常抗拒在文章里插入大量由外部绘图工具截取的位图图片。那些图片不仅体积沉重，而且无法根据「褐页」与「暖墨」双主题自动调色；更致命的是，图片里的文字无法搜索，一旦架构微调就必须重新截图替换。
因此，我将 Mermaid 深度集成到了 Maplen 的 Markdown / MDX 渲染管线中。所有的流程图、序列图与状态机都直接以文本代码的形式存在，受 Git 统一版本控制，并在构建与主题切换时实时矢量渲染。
这篇手记通过四个直观的架构视图，为你展示 Maplen 整个站点的骨架与运转机理。
一、4N 与 Columns 的正交内容模型
Maplen 最核心的内容哲学，在于解开文章类别与主题探索之间的死结。
- 4N 决定单篇文章的表达语气：无论是直抒胸臆的经历复盘（Narrative），对光影佳作的触动（Nebula），对复杂问题的理性思辨（Notes），还是亲手构筑代码与电路的实践（Nodes）；
- Columns（专栏） 则打破分类的边界，沿着时间、项目或主题的脉络，将散落在不同栏目中的文章串联成一条完整的认知线索。
这种正交设计让写作获得了极大的自由：一个持续半年的硬件项目，可以同时包含架构图解（Nodes）、人机关系随笔（Notes）、科幻电影共鸣（Nebula）和结项纪事（Narrative），它们共同编织成了专栏的骨肉。
二、静态优先：从源文本到发布产物
Maplen 没有复杂的后端服务、数据库或管理后台。所有文章都保存在项目仓库中，通过 Astro 的 Content Layer 进行强类型校验与预编译。
整个管线遵循清晰的 输入 · 转换 · 交付 三栏式分工，设计原则是：能在构建期完成的事情，绝不留到浏览器去算。
| 输入层（Input） | 核心转换管线（Pipeline） | 交付物矩阵（Output） |
|---|---|---|
| Markdown (.md) 承载沉浸长篇叙事 | Zod Schema 校验 严格校验 frontmatter 标题、标签、日期约束 | 纯净 HTML 页面 极速秒开，双主题预载零闪白 |
| MDX (.mdx) 引入局部图表与仿真 | Remark + Rehype KaTeX 公式预渲染、Wiki 双向链接解析 | 按需水合 Islands 滚动到视口触发微量 React 运行时 |
| Wiki 概念词条 数字花园词条定义 | Shiki 高亮引擎 双主题色彩映射、代码 Diff 与焦点行 | RSS / llms.txt 面向人类订阅与 AI Agent 的全景分发 |
- 数学公式通过 KaTeX 预渲染为静态 MathML / HTML，彻底消除了客户端 MathJax 闪烁问题；
- 代码块由 Shiki 在服务端直接完成语法高亮与行号着色，开箱即支持双主题与代码 Diff；
- 生成物除了标准的静态网页，还包括全站与各分栏的 RSS、Sitemap 以及面向现代 AI 工具的
llms.txt。
三、渐进水合：静态首屏与交互岛屿
技术文章有时需要动态实验——比如后面会展示的阻尼振子模拟与交互式函数图像。但我绝不希望为了局部的交互功能，让整站变成一个体积庞大的单页应用（SPA）。
我采用了 Astro 的 React Islands 架构，并配置了 client:visible 懒加载策略：
首屏加载时，页面纯净得只有骨架 HTML 和样式文件，加载速度以毫秒计。只有当读者真正把页面滚动到交互图表附近时，浏览器才会异步拉取对应的微型 React 运行时与组件代码，完成原地水合。
四、生命周期：一篇文章在 Maplen 的演进
文章不是一次性的快餐消费品。在我的设想中，Maplen 里的每一篇文字都像园子里的植物，会随着时间持续生长。
一个灵感可能最初只是 Notes 里的几句片段；随着亲手编码验证，它演变成 Nodes 里的实践手记；当多个相关探索汇聚，便自然升华为一个 Columns 专栏；再通过 [[wikilinks]] 与其他概念词条相互引证，最终织就一张能够长期生长的知识之网。
五、在 Markdown 中编写图表
在实际写作中，我只需要在 Markdown/MDX 文件中书写标准的 Mermaid 代码块，或者调用封装好的 <Mermaid /> 组件：
export const flow = `
flowchart TB
A["源文本"] --> B["Astro 构建"]
B --> C["静态 HTML"]
`;
<Mermaid
chart={flow}
caption="图 1：内容管线。"
/>代码即图表，图表即思考。这正是让写作回归纯粹与坚固的技术方式。