知识库主题：给团队做个干净的文档站

背景：团队需要一个内部文档站存放设计规范和组件文档。开源的 Docusaurus 太重，Notion 太慢，Confluence 太丑。我用 huashu-design 做了一个干净的知识库主题，单 HTML 文件，双击打开，不依赖任何框架。

为什么文档站的设计难度被低估了？

文档站是所有界面里最「功能导向」的。用户打开文档站不是为了欣赏你的设计，而是为了找到信息然后离开。

所以文档站的设计标准只有一个：用户能不能在 3 次点击内找到他要的东西？

大多数 AI 做的文档站的问题是：过度设计。左侧导航加了个展开/收起动画，右侧内容区的字号对比不够，代码块高亮配色辣眼睛——都是减分项。

第一步：信息架构（不写代码先画图）

开工前，AI 先确认文档站的信息层级：

一级导航        →  快速入门 · 组件 · 样式 · 资源
二级导航（每页） →  概述 · API · 示例 · 最佳实践
三级（内容）    →  标题 → 子标题 → 代码块 → 提示

AI 先把目录结构画出来，给我确认。我调整了「组件」下面的顺序：把最常用的 Button 放在最前面。

这个步骤是文档站设计中最容易被跳过的。 不做信息架构直接画页面，出来的结果永远是漂亮但不好用的。

第二步：版式系统——三个核心规则

设计文档站不需要创意，需要纪律。huashu-design 用了一套极简的版式系统：

没有花哨的卡片，没有渐变，没有阴影。文档的版式越安静，内容越突出。

第三步：导航——左边栏的精髓

左侧导航是文档站的核心交互。huashu-design 的设计原则：

1. 展开所有层级：默认展开所有子目录，不让用户猜「这一节下面还有没有内容」
2. 当前页面高亮：白底 + 粗字，不是花哨的彩色背景
3. 搜索框：固定在顶部，Cmd+K 快捷键激活

导航宽度 240px，不多不少。太窄了文字折行，太宽了抢内容区空间。

第四步：代码块——开发者文档的灵魂

代码块是知识库中最常被忽略的设计元素。huashu-design 的处理：

• 深色背景：不是浅灰，是接近纯黑的 #1A1918，和白底页面形成强烈对比
• 行号：右侧，半透明，不干扰代码阅读
• 复制按钮：hover 时出现，右上角
• 语言标签：代码块顶部，小字标注「css / jsx / bash...」

/* 代码块示例 */
.container {
  max-width: 720px;
  margin: 0 auto;
  padding: 0 24px;
}

一个好的代码块设计，让开发者觉得「这个文档站懂我」。

第五步：提示框——信息分层

文档里经常需要放提示、警告、注意。huashu-design 用三种提示框：

💡 提示：这是建议做法
⚠️ 注意：这是容易踩坑的地方
🚫 不要：这是反模式

每种提示框用不同的左边框颜色区分（绿/黄/红），但整体风格统一——不抢正文的视觉焦点。

为什么单 HTML 文件就够了？

对于 50 页以内的文档站，单 HTML 文件是最实用的方案：

• 不需要构建工具，不需要 npm install
• 双击就能在浏览器打开
• 放在内网服务器上就是文档站
• 改内容直接编辑 HTML 中的 markdown 块

对于更大的文档站，huashu-design 提供了多 HTML + 索引页的方案，但 90% 的团队场景单文件足够。

耗时复盘

核心心得

知识库设计的本质是：让信息自己说话。

干净的排版、克制的交互、安静的颜色——文档站不需要证明设计水平，它需要让用户最快地找到答案。如果你做的文档站被人夸「设计很好看」，而不是「找东西很快」，那它就是失败的。

下次团队需要文档站的时候，别折腾 Docusaurus 配置了，一个 HTML 文件就够了。

截图清单

1. ✅ 知识库文档站（三栏布局 + 导航 + 代码块 + 提示框）— 已插入上文