---
url: /overview.md
---

# 使用说明

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

## 一、新增一个项目

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

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

```ts
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`、历史归档等）

## 四、本地预览与构建

```bash
# 构建 + 起预览服务（端口 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。