接入指南
把你的组件库接进来
组件库不用改代码,也不用改这个站点。只要有一个能访问到的 README, 往配置里加一条记录,它就会出现在左侧列表里,正文在每次请求时从源仓库实时读取。
三步接入
- 1
准备一份 README
放在组件库仓库里就行。支持 GitHub、GitLab,以及任意能返回 Markdown 的 HTTP 地址;私有仓库需要一个有读权限的 token。
- 2
加一条配置
写进
config/components.json的数组。下面这条是本站正在使用的配置, 换成你的仓库地址即可。 - 3
刷新页面
配置生效后刷新页面,新条目会按配置里的顺序出现在左侧。私有仓库请先按下方教程配置令牌。
{
"slug": "3d-stage-editor",
"name": "3D 预演台",
"type": "readme",
"cacheTtl": 60,
"source": {
"provider": "github",
"repo": "TianJiang-Tech/3d-stage-editor",
"branch": "main",
"path": "README.md",
"tokenEnv": "STAGE_EDITOR_READ_TOKEN"
}
}
| 字段 | 必填 | 说明 |
|---|---|---|
slug | 是 | 页面地址,只能用小写字母、数字和连字符,例如 3d-stage-editor |
name | 是 | 侧栏与页面标题显示的名字 |
type | 是 | 组件填 readme;第一项 home 是本站首页,保持 page |
cacheTtl | 否 | 该组件的缓存秒数,默认取环境变量 CACHE_TTL |
source.provider | 是 | github / gitlab / raw |
source.repo | GitHub | 形如 org/repo |
source.project | GitLab | 形如 group/project |
source.branch | GitHub / GitLab | 分支名,例如 main |
source.path | GitHub / GitLab | README 在仓库里的路径,例如 README.md |
source.url | HTTP 源 | README 的完整地址,用于任意 HTTP 源 |
source.authHeader | 否 | HTTP 源的认证头,默认 Authorization |
source.authScheme | 否 | 认证方案,默认 Bearer |
source.tokenEnv | 私有仓库 | 存放 token 的环境变量名,不要写 token 本身 |
为私有仓库配置令牌
为每个仓库创建独立的只读令牌。文档站用它读取 README 和文档引用的仓库附件。
GitHub
- 打开 Fine-grained token 创建页, 填写名称和有效期。
- 在 Resource owner 选择仓库所属的个人账号或组织。在 Only select repositories 中只勾选要接入的仓库。
- 在 Repository permissions 将 Contents 设为 Read-only,生成后立即复制令牌。如果显示
Pending, 等组织管理员批准后再接入。
GitLab
- 在目标项目打开 Settings → Access tokens → Add new token。 创建项目令牌需要 Maintainer 或 Owner 权限。
- 填写名称和有效期,角色选 Reporter,权限范围只勾选
read_repository,用于通过 Repository Files API 读取文档文件。 - 点击创建并立即复制令牌。若找不到入口,请让项目维护者检查项目权限和组织策略。 GitLab 项目令牌说明
在文档站绑定并验证
- 按
<仓库简称>_READ_TOKEN命名,例如STAGE_EDITOR_READ_TOKEN。 将变量名填入该组件的source.tokenEnv。 - 在服务端配置同名环境变量。本站部署使用
component-docs/shared/.env, 更新后重建文档站容器以加载新值。令牌原文保存在服务端,避免提交到 Git 或发到聊天中。 - 打开左侧对应的组件,确认 README 和截图可以读取。遇到 404 时,核对令牌权限、 仓库选择、分支和 README 路径。
# .env
STAGE_EDITOR_READ_TOKEN=<只读 token>
本站页面可以公开访问。接入私有仓库前,请确认 README 和其中引用的附件都可以公开。
README 约定
- README 自带的一级标题会作为页面标题,站点不再重复渲染组件名。
- 相对路径的图片和链接会按源仓库地址重写。图片建议提交进仓库,外链图床在私有环境里可能打不开。
- 正文按 GFM 渲染,表格、代码高亮、折叠面板都能用;上游 HTML 会先做白名单过滤再输出。
- 源站暂时不可达时,页面继续显示上一版内容,并标注出来。