fix: allow Kapa widget through CSP
中文 | English
This is the source code repository for the HugeGraph documentation website.
For the HugeGraph database project, visit apache/hugegraph.
Only 3 steps to run the documentation website locally:
Prerequisites: Node.js v18+
# 1. Clone repository git clone https://github.com/apache/hugegraph-doc.git cd hugegraph-doc # 2. Install dependencies npm install # 3. Start development server (auto-reload) npm run start
Open http://localhost:3000 to preview.
hugegraph-doc/ ├── content/ # 📄 Documentation content (Markdown) │ ├── cn/ # 🇨🇳 Chinese documentation │ │ ├── docs/ # Main documentation │ │ │ ├── quickstart/ # Quick start guides │ │ │ ├── config/ # Configuration docs │ │ │ ├── clients/ # Client docs │ │ │ ├── guides/ # User guides │ │ │ └── ... │ │ ├── blog/ # Blog posts │ │ └── community/ # Community pages │ └── en/ # 🇺🇸 English documentation (mirrors cn/ structure) │ ├── src/ # 🎨 Docusaurus pages, CSS, and helpers ├── static/ # 📁 Static files served from site root ├── src/data/versions.json # 🏷️ Documentation version metadata ├── scripts/ # 🔧 Content validation and version preparation ├── docusaurus.config.js # ⚙️ Site configuration ├── sidebars*.js # 🧭 Documentation sidebar configuration └── package.json # 📦 Node.js dependencies
The source tree keeps only current documentation and version metadata. Docusaurus release snapshots are generated before npm run start and npm run build from the configured Git source refs. A version entry may set sourceRef to read from a Git branch or tag; when it is omitted, the current working tree is used.
Version semantics:
| Version | Route | Meaning |
|---|---|---|
stable | /docs/, /cn/docs/ | Latest stable release documentation and the default navbar target |
current / next | /docs/next/, /cn/docs/next/ | Unreleased development documentation with an unreleased banner |
Release-branch mapping is explicit:
| Source branch | Docusaurus version / route segment | UI label |
|---|---|---|
release-1.5.0 | docusaurus-1.5.0 | 1.5.0 |
release-1.3.0 | docusaurus-1.3.0 | 1.3.0 |
release-1.2.0 | docusaurus-1.2.0 | 1.2.0 |
release-1.0.0 | docusaurus-1.0.0 | 1.0.0 |
release-0.11 | docusaurus-0.11 | 0.11 |
release-0.10 | docusaurus-0.10 | 0.10 |
The source branch prefix is never shown in the UI. The archived release branches listed above were authored before this Docusaurus migration, so any import repair for those snapshots is isolated under legacyCompatibility in src/data/versions.json. That compatibility layer is only for adapting those historical branches to a previewable Docusaurus build; it is not part of the normal documentation authoring or version generation pipeline. Future Docusaurus-native release branches should keep the standard content/{en,cn}/docs layout and should not require those adapters.
In the mapping table, docusaurus-* is a Docusaurus version name and route segment, not necessarily a Git branch. The actual content source is always the configured sourceRef. For example, 1.5.0 currently reads from the Git branch release-1.5.0 and is published under the Docusaurus route segment docusaurus-1.5.0.
Generate the Docusaurus version files locally:
npm run docs:versions:prepare
This writes versioned_docs/, versioned_sidebars/, versions.json, docs-cn_versioned_docs/, docs-cn_versioned_sidebars/, and docs-cn_versions.json from the configured source refs. These files are generated build inputs and are intentionally ignored by Git.
List configured versions:
npm run docs:versions:list
To update a release source:
src/data/versions.json, especially label, docusaurusVersion, path, cnPath, githubTagUrl, and sourceRef.fetch-depth: 0, so tags and release branches are available there.npm run docs:versions:prepare, then npm run build.To freeze the current next documentation as a new stable release, such as 1.8.0, first create a durable Docusaurus-native source branch from the release-ready documentation state:
git checkout master git pull git checkout -b docusaurus-1.8.0 git push origin docusaurus-1.8.0
Then update src/data/versions.json on master: point stable.sourceRef to docusaurus-1.8.0, change the stable label to Stable (1.8.0), and, if the previous stable release should remain available, add an archived 1.7.0 entry whose sourceRef is docusaurus-1.7.0. Docusaurus-native frozen branches should not need legacyCompatibility.
After the version metadata is merged to master, the production deployment is automatic. .github/workflows/docusaurus.yml runs npm run build on master, generates all version snapshots from their configured sourceRef values, and publishes ./build to the asf-site branch. .asf.yaml publishes the production website from asf-site; asf-staging is only for manual preview validation before the merge.
Only archived pre-Docusaurus branches should use legacyCompatibility fields such as sourcePaths, sourceIncludes, sourceOverlays, excludePaths, indexFrom, or Markdown normalization. These fields document deliberate compatibility work for old snapshots, not guidance for new documentation. Use excludePaths for old-version docs that have been moved to global site sections, such as Download or Community contribution pages, so they do not appear again inside archived Documentation.
Do not use latest ambiguously in docs navigation. Use stable for the latest released documentation and next for unreleased documentation.
The Team page is available at /team/ and /cn/team/. It is data-driven from src/data/team.js, currently based on public ASF roster data. Update that file when PMC or committer information changes, and include the public source used for the update.
The user showcase is available at /users/ and /cn/users/. It is data-driven from src/data/users.js and uses public submissions from apache/hugegraph#1651. Do not add company names, logos, quotes, or deployment details unless they are already public and approved. If no approved logo exists in the repository, leave the logo empty and let the page render the fallback initials.
The Kapa Ask AI website widget is configured in docusaurus.config.js. The HugeGraph widget integration ID is temporarily hardcoded there so the staged preview can be validated, with a TODO to move it to a GitHub repository variable after the Kapa setup is finalized. KAPA_WEBSITE_ID can still override the hardcoded value at build time.
To preview the widget locally with a different integration ID:
KAPA_WEBSITE_ID=<kapa-website-id> npm run build npm run serve
For production, move the hardcoded value to KAPA_WEBSITE_ID as a repository variable so .github/workflows/docusaurus.yml can pass it to npm run build. The value is the public Kapa Website Widget integration ID, not a private API key. If a Content Security Policy is added later, allow the Kapa widget domain plus the selected bot-protection provider, following the Kapa and Pulsar examples.
The site supports these publishing states:
| State | Front matter | Production behavior |
|---|---|---|
| Public | default | Appears in navigation and generated outputs |
| Draft | draft: true | Excluded from production builds by Docusaurus |
| Unlisted | unlisted: true | Built for direct URL access but hidden from navigation, listings, feeds, and indexed discovery; Docusaurus adds noindex/nofollow metadata |
| Placeholder | placeholder: true, unlisted: true, noindex: true | Reserves a URL with only a short safe placeholder message |
| Private | private: true | Fails production builds unless ALLOW_PRIVATE_CONTENT=true is explicitly set for a non-public preview |
Private content is not access control. Do not put sensitive material in Markdown, MDX, static assets, generated HTML, JavaScript bundles, source maps, or JSON that will be published. Real private access must be enforced by the hosting platform, reverse proxy, authentication gateway, or a non-public preview environment.
Production builds run:
npm run check:content-visibility
Use this placeholder pattern when reserving a route:
--- title: Upcoming Case Study unlisted: true noindex: true placeholder: true --- This page is reserved for an upcoming Apache HugeGraph case study.
master| Requirement | Description |
|---|---|
| Bilingual Updates | Update BOTH content/cn/ and content/en/ |
| PR Screenshots | Include before/after screenshots in PR |
| Markdown | Use Markdown with front matter |
See contribution.md for:
| Command | Description |
|---|---|
npm run start | Start dev server (hot reload) |
npm run build | Build production site to ./build/ |
npm run serve | Serve the production build locally |
npm run check:content-visibility | Fail production-unsafe private content |
npm run docs:versions:prepare | Generate Docusaurus version files from configured Git refs |
npm run docs:versions:list | Print configured docs versions |
npm run validate | Build, check content inventory, and run headless UI validation |
这是 HugeGraph 官方文档网站 的源代码仓库。
如果你想查找 HugeGraph 数据库本身，请访问 apache/hugegraph。
只需 3 步即可在本地启动文档网站：
前置条件： Node.js v18+
# 1. 克隆仓库 git clone https://github.com/apache/hugegraph-doc.git cd hugegraph-doc # 2. 安装依赖 npm install # 3. 启动开发服务器（支持热重载） npm run start
打开 http://localhost:3000 预览网站。
hugegraph-doc/ ├── content/ # 📄 文档内容 (Markdown) │ ├── cn/ # 🇨🇳 中文文档 │ │ ├── docs/ # 主要文档目录 │ │ │ ├── quickstart/ # 快速开始指南 │ │ │ ├── config/ # 配置文档 │ │ │ ├── clients/ # 客户端文档 │ │ │ ├── guides/ # 使用指南 │ │ │ └── ... │ │ ├── blog/ # 博客文章 │ │ └── community/ # 社区页面 │ └── en/ # 🇺🇸 英文文档（与 cn/ 结构一致） │ ├── src/ # 🎨 Docusaurus 页面、样式和辅助脚本 ├── static/ # 📁 站点根路径静态文件 ├── src/data/versions.json # 🏷️ 文档版本元数据 ├── scripts/ # 🔧 内容校验和版本准备脚本 ├── docusaurus.config.js # ⚙️ 站点配置 ├── sidebars*.js # 🧭 文档侧边栏配置 └── package.json # 📦 Node.js 依赖
源码分支只保留当前文档和版本元数据。Docusaurus 需要的版本快照会在 npm run start 和 npm run build 前，从配置的 Git source ref 生成。版本条目可以通过 sourceRef 指向 Git 分支或标签；未设置时使用当前工作区文档。
| 版本 | 路由 | 含义 |
|---|---|---|
stable | /docs/, /cn/docs/ | 最新稳定版本文档，也是导航栏默认入口 |
current / next | /docs/next/, /cn/docs/next/ | 未发布开发中文档，并展示 unreleased 提示 |
发布分支映射规则是显式配置的：
| 源分支 | Docusaurus 版本 / 路由段 | UI 展示 |
|---|---|---|
release-1.5.0 | docusaurus-1.5.0 | 1.5.0 |
release-1.3.0 | docusaurus-1.3.0 | 1.3.0 |
release-1.2.0 | docusaurus-1.2.0 | 1.2.0 |
release-1.0.0 | docusaurus-1.0.0 | 1.0.0 |
release-0.11 | docusaurus-0.11 | 0.11 |
release-0.10 | docusaurus-0.10 | 0.10 |
UI 不展示源分支的 release- 前缀。上表中的归档 release 分支是在这次 Docusaurus 迁移之前编写的，所以为了让这些历史快照可以被 Docusaurus 预览，相关导入修补都被限制在 src/data/versions.json 的 legacyCompatibility 下。这一层只用于适配这些旧分支，不属于正常的文档编写或版本生成流水线。未来 Docusaurus 原生的发布分支应保持标准的 content/{en,cn}/docs 目录，不应依赖这些适配项。
上表里的 docusaurus-* 是 Docusaurus 版本名和路由段，不一定是 Git 分支名。实际内容来源始终由配置中的 sourceRef 决定。例如 1.5.0 当前从 Git 分支 release-1.5.0 读取内容，并发布到 Docusaurus 路由段 docusaurus-1.5.0。
本地生成 Docusaurus 版本文件：
npm run docs:versions:prepare
该命令会生成 versioned_docs/、versioned_sidebars/、versions.json、docs-cn_versioned_docs/、docs-cn_versioned_sidebars/ 和 docs-cn_versions.json。这些是构建输入，不作为源码提交。
更新发布版本时，请修改 src/data/versions.json 中的 label、docusaurusVersion、path、cnPath、githubTagUrl 和 sourceRef。该 ref 需要已经 fetch 到本地，然后运行 npm run docs:versions:prepare 和 npm run build。
如果要把当前 next 文档固化为新的稳定版本，比如 1.8.0，请先从已准备发布的文档状态创建一个长期存在的 Docusaurus 原生 source branch：
git checkout master git pull git checkout -b docusaurus-1.8.0 git push origin docusaurus-1.8.0
然后在 master 上更新 src/data/versions.json：将 stable.sourceRef 指向 docusaurus-1.8.0，将 stable label 改成 Stable (1.8.0)；如果旧 stable 仍需保留入口，则新增归档版本 1.7.0，并让它的 sourceRef 指向 docusaurus-1.7.0。这种 Docusaurus 原生固化分支不应需要 legacyCompatibility。
版本元数据合入 master 后，生产部署会自动完成。.github/workflows/docusaurus.yml 会在 master 上执行 npm run build，根据各版本配置的 sourceRef 生成版本快照，并把 ./build 发布到 asf-site 分支。.asf.yaml 会从 asf-site 发布正式站点；asf-staging 只用于 merge 前的手动预览验证。
只有归档的 pre-Docusaurus 分支才应该使用 legacyCompatibility 下的 sourcePaths、sourceIncludes、sourceOverlays、excludePaths、indexFrom 或 Markdown normalization。这些字段用于记录旧快照的兼容目的，不是新文档的开发规范。对于已经迁移到全局站点区域的旧版本文档，例如 Download 或 Community contribution 页面，应通过 excludePaths 从归档 Documentation 中移除，避免重复出现。
不要在导航中模糊使用 latest：stable 表示最新已发布版本，next 表示未发布开发中文档。
Team 页面位于 /team/ 与 /cn/team/，数据来自 src/data/team.js，当前基于 ASF 公开 roster。PMC 或 committer 变化时请更新该数据文件，并保留公开来源。
用户案例页面位于 /users/ 与 /cn/users/，数据来自 src/data/users.js，当前基于 apache/hugegraph#1651 的公开提交。不要加入未经公开授权的公司名、Logo、引用或部署细节；如果仓库中没有已授权 Logo，则保持为空，页面会展示缩写占位。
Kapa Ask AI 网站小组件在 docusaurus.config.js 中配置。当前为了验证 staged 预览，HugeGraph widget integration ID 暂时硬编码在配置里，并带有 TODO，后续应迁移到 GitHub repository variable。构建时仍可通过 KAPA_WEBSITE_ID 覆盖这个硬编码值。
使用其他 integration ID 本地预览：
KAPA_WEBSITE_ID=<kapa-website-id> npm run build npm run serve
生产环境后续应把硬编码值迁移到仓库 variable KAPA_WEBSITE_ID，.github/workflows/docusaurus.yml 会把它传给 npm run build。这个值是公开的 Kapa Website Widget integration ID，不是私有 API key。如果以后给站点增加 Content Security Policy，需要参考 Kapa 和 Pulsar 的示例，把 Kapa widget 域名以及所选 bot-protection provider 加入允许列表。
| 状态 | Front matter | 生产行为 |
|---|---|---|
| Public | 默认 | 正常出现在导航和生成内容中 |
| Draft | draft: true | Docusaurus 在生产构建中排除 |
| Unlisted | unlisted: true | 可通过直链访问，但不进入导航、列表、feed 和索引发现；Docusaurus 会添加 noindex/nofollow |
| Placeholder | placeholder: true, unlisted: true, noindex: true | 只保留短占位内容，用于预留 URL |
| Private | private: true | 生产构建失败，除非在非公开预览环境显式设置 ALLOW_PRIVATE_CONTENT=true |
静态站点前端不提供真正的加密或访问控制。不要把敏感内容放进会发布的 Markdown、MDX、静态资源、HTML、JS bundle、source map 或 JSON 中；真正的私有访问必须由托管平台、反向代理、认证网关或非公开预览环境实现。
master 创建新分支| 要求 | 说明 |
|---|---|
| 双语更新 | 修改内容时需同时更新 content/cn/ 和 content/en/ |
| PR 截图 | 提交 PR 时需附上修改前后对比截图 |
| Markdown | 文档使用 Markdown 格式，带 front matter |
查看 contribution.md 了解：
| 命令 | 说明 |
|---|---|
npm run start | 启动开发服务器（热重载） |
npm run build | 构建生产版本到 ./build/ |
npm run serve | 本地预览生产构建 |
npm run check:content-visibility | 检查并阻断生产不安全的私有内容 |
npm run docs:versions:prepare | 从配置的 Git ref 生成 Docusaurus 版本文件 |
npm run docs:versions:list | 输出当前配置的文档版本 |
npm run validate | 构建、检查内容清单并运行无头 UI 校验 |
Thanks to all contributors to the HugeGraph documentation!