接入指南

把你的组件库接进来

组件库不用改代码,也不用改这个站点。只要有一个能访问到的 README, 往配置里加一条记录,它就会出现在左侧列表里,正文在每次请求时从源仓库实时读取。

当前收录 2 个组件config/components.json

三步接入

  1. 1

    准备一份 README

    放在组件库仓库里就行。支持 GitHub、GitLab,以及任意能返回 Markdown 的 HTTP 地址;私有仓库需要一个有读权限的 token。

  2. 2

    加一条配置

    写进 config/components.json 的数组。下面这条是本站正在使用的配置, 换成你的仓库地址即可。

  3. 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.repoGitHub形如 org/repo
source.projectGitLab形如 group/project
source.branchGitHub / GitLab分支名,例如 main
source.pathGitHub / GitLabREADME 在仓库里的路径,例如 README.md
source.urlHTTP 源README 的完整地址,用于任意 HTTP 源
source.authHeader否HTTP 源的认证头,默认 Authorization
source.authScheme否认证方案,默认 Bearer
source.tokenEnv私有仓库存放 token 的环境变量名,不要写 token 本身

为私有仓库配置令牌

为每个仓库创建独立的只读令牌。文档站用它读取 README 和文档引用的仓库附件。

GitHub

  1. 打开 Fine-grained token 创建页, 填写名称和有效期。
  2. 在 Resource owner 选择仓库所属的个人账号或组织。在 Only select repositories 中只勾选要接入的仓库。
  3. 在 Repository permissions 将 Contents 设为 Read-only,生成后立即复制令牌。如果显示 Pending, 等组织管理员批准后再接入。

GitLab

  1. 在目标项目打开 Settings → Access tokens → Add new token。 创建项目令牌需要 Maintainer 或 Owner 权限。
  2. 填写名称和有效期,角色选 Reporter,权限范围只勾选 read_repository,用于通过 Repository Files API 读取文档文件。
  3. 点击创建并立即复制令牌。若找不到入口,请让项目维护者检查项目权限和组织策略。 GitLab 项目令牌说明

在文档站绑定并验证

  1. 按 <仓库简称>_READ_TOKEN 命名,例如 STAGE_EDITOR_READ_TOKEN。 将变量名填入该组件的 source.tokenEnv。
  2. 在服务端配置同名环境变量。本站部署使用 component-docs/shared/.env, 更新后重建文档站容器以加载新值。令牌原文保存在服务端,避免提交到 Git 或发到聊天中。
  3. 打开左侧对应的组件,确认 README 和截图可以读取。遇到 404 时,核对令牌权限、 仓库选择、分支和 README 路径。
# .env
STAGE_EDITOR_READ_TOKEN=<只读 token>

本站页面可以公开访问。接入私有仓库前,请确认 README 和其中引用的附件都可以公开。

README 约定

  • README 自带的一级标题会作为页面标题,站点不再重复渲染组件名。
  • 相对路径的图片和链接会按源仓库地址重写。图片建议提交进仓库,外链图床在私有环境里可能打不开。
  • 正文按 GFM 渲染,表格、代码高亮、折叠面板都能用;上游 HTML 会先做白名单过滤再输出。
  • 源站暂时不可达时,页面继续显示上一版内容,并标注出来。