使用说明

本页说明这套门户怎么用、怎么加项目。全部逻辑都在这一个文件里：hub-v2/.vitepress/config.mts。

一、新增一个项目

两步，改完重新构建即可（导航、侧边栏、路由全部自动生成，不用改别处）：

1. 在仓库根建一个目录，例如 myproject/，里面按需放 .md 文档、子目录
2. 打开 hub-v2/.vitepress/config.mts，在 ENTRIES 里加一行：

const ENTRIES: { key: string; text: string; flat?: boolean }[] = [
  { key: "overview", text: "总览", flat: true },   // flat: true = 不是项目，目录首页直接当第一项
  { key: "example", text: "示例项目" },
  { key: "myproject", text: "我的新项目" },          // ← 新加这一行
];

刷新页面，顶部菜单会出现「我的新项目」，左栏自动列出该目录下的所有文档树。

ENTRIES 里写了但目录不存在的项会被自动跳过（liveEntries 过滤），所以先加菜单、后写文档也不会报错。

二、写一篇文档

规则	说明
标题	文件首行 # 标题，门户直接取它作为侧边栏文字（取不到则用文件名）
排序	前端加 order: 10（数字小的排前面，不写默认排最后）
层级	目录即分组（可折叠），目录深度不限；松散 .md 直接成为页面项
Mermaid	直接用 ```mermaid 代码块，图形在浏览器端渲染
目录首页	目录里可以放 index.md，作为该分组的落地页

三、不参与导航的目录

config.mts 里两个白名单/黑名单：

• SKIP_DIRS：统计侧边栏时跳过的目录名（默认 media、assets，用来放图片附件）
• srcExclude：完全不参与构建的路径（程序目录本身、node_modules、历史归档等）

四、本地预览与构建

# 构建 + 起预览服务（端口 5090）
bash run-service.sh

# 只构建，产物在 hub-v2/.vitepress/dist
npx vitepress build hub-v2

# 只预览（不重新构建）
npx vitepress preview hub-v2 --port 5090

改了 .md 必须重新构建，产物才是最新的。

五、部署形态

生产用 Nginx 托管 hub-v2/.vitepress/dist 静态产物即可（无需 Node 运行时）。 本方案交付的是 Docker 容器化部署，详见仓库根 README.md。

站点若挂在子路径（例如 https://example.com/kb/），需在 config.mts 里设置 base: "/kb/"，否则资源路径会 404。