- GIS
【免费下载链接】h3
Hexagonal hierarchical geospatial indexing system
本指南围绕 H3 官方文档网站（即website/目录）展开，讲解如何基于 Docusaurus 在本地构建与预览 H3 文档、理解站点结构与配置、编写和更新文档内容，以及了解代码合并到master分支后由 GitHub Actions 自动发布到 GitHub Pages 的完整流程。读完本文，你将能够独立在本地跑起 H3 文档站点、定位文档源文件、定制站点行为，并掌握与 CI 部署相关的关键配置。
H3 文档网站是什么
H3 是 Uber 开源的六边形层级地理空间索引系统（Hexagonal hierarchical geospatial indexing system）。它的官方文档网站源码就托管在本仓库的 website 目录中，成品站点即 h3geo.org（域名记录于 website/static/CNAME）。
根据 website/README.md 的说明，站点具有三个关键事实：
- 文档页面的内容源位于 docs 目录；
- 网站使用 Docusaurus 构建；
- 站点内容全部为静态页面，适合托管在 GitHub Pages 这类静态托管服务上。
也就是说，仓库中 website 目录本身就是一个完整、独立的 Docusaurus 前端工程，而不是 H3 C 核心库的一部分；它通过 npm 依赖h3-js等 JavaScript 绑定来在浏览器中演示 H3 的能力。
环境要求与依赖概览
本地构建文档网站的唯一硬性要求是Node.js（website/README.md）。除此之外，工程通过yarn管理依赖。
从 website/package.json 可以看到工程的具体约定：
- 包名为
h3-website，通过volta字段锁定了 Node16.18.1与 yarn1.22.10，并通过packageManager声明使用yarn@1.22.22——本地开发时建议优先使用相同大版本的工具链，避免 lockfile 不兼容； - 核心依赖包括
@docusaurus/core与@docusaurus/preset-classic（版本^3.10.1）、@docusaurus/theme-live-codeblock（支持在文档中嵌入可实时执行的代码块）； - 与 H3 直接相关的依赖：
h3-js（4.4.0，当前版本绑定）和h3-jsv3（npm:h3-js@^3.7.1，用于演示 3.x 与 4.x 的 API 差异）； - 地图可视化相关：
deck.gl、mapbox-gl、react-map-gl、geojson2h3、wkt； - 数学公式支持：
remark-math与rehype-katex； - 站内搜索：
docusaurus-lunr-search； - 代码风格：
prettier。
此外，browserslist分别定义了生产与开发环境的浏览器兼容范围，构建时会据此自动生成相应前缀与降级代码。
本地构建与预览：三条核心命令
从./website目录执行（website/README.md）：
yarn yarn startyarn会根据yarn.lock安装全部依赖（该文件已提交在 website/yarn.lock，保证环境可复现）；yarn start启动 Docusaurus 开发服务器，并在浏览器中打开http://localhost:3000；- 开发服务器支持热更新：编辑 website/docs 下的 Markdown/MDX 文件时，页面会自动刷新，无需重启。
要验证一个接近生产环境的构建产物，可以运行：
yarn build该命令（对应docusaurus build）会执行完整的静态站点打包，产出到website/build目录。构建完成后，还可以用yarn serve（即docusaurus serve）在本地以静态服务器方式预览生产构建的结果，从而更真实地模拟线上效果。
其他常用脚本一览
website/package.json 的scripts字段还提供了若干实用命令：
| 命令 | 等价命令 | 用途 |
|---|---|---|
yarn start | docusaurus start | 启动开发服务器（热更新） |
yarn build | docusaurus build | 生成生产级静态站点 |
yarn serve | docusaurus serve | 本地预览构建产物 |
yarn swizzle | docusaurus swizzle --danger | 抽取/自定义 Docusaurus 主题组件 |
yarn deploy | docusaurus deploy | 手动发布到 GitHub Pages |
yarn clear | docusaurus clear | 清空本地构建缓存 |
yarn write-translations | docusaurus write-translations | 生成多语言翻译所需的 JSON 骨架 |
yarn write-heading-ids | docusaurus write-heading-ids | 为文档标题补全锚点 ID |
yarn format | prettier --write src | 对src下的代码统一格式化 |
yarn format不只是本地习惯，它还出现在 CI 的格式检查步骤中（见下文“持续集成”一节），保证合并进仓库的代码风格一致。
文档内容在哪里：docs 目录与版本化文档
站点正文全部位于 website/docs，按主题划分为多个子目录，与 website/sidebars.js 中定义的侧边栏结构一一对应：
- Getting Started：
README（站点首页简介）、highlights/（H3 特性：聚合、关联、流量建模、机器学习、索引）、comparisons/（与 S2、Geohash、Hexbin、行政边界、Placekey 的对比）、installation、quickstart； - Concepts and Guides：
library/下的术语表、错误码、分辨率表，以及 H3 索引结构（h3Indexing、cell、directededge、vertex）和从 3.x 迁移的指南； - API Reference：
api/下的indexing、inspection、traversal、hierarchy、regions、uniedge、vertex、misc； - Community：
community/下的 bindings、libraries、tutorials、applications； - H3 Internals：
core-library/下的核心库概览、坐标系、绑定创建、filters、编译选项、测试、自定义分配器、使用方式，以及三个算法详解（latLngToCellDesc、cellToLatLngDesc、cellToBoundaryDesc）。
每个文档文件头部都带有 YAML front matter（如id、title、sidebar_label、slug），例如 website/docs/README.md 通过slug: /把首页文档映射到站点的根路径。新增文档时，只需在对应目录添加 Markdown（.md）或 MDX（.mdx）文件，并在sidebars.js中登记路径即可。
历史版本：3.x 文档
仓库同时保留了 3.x 版本的整套文档，位于 website/versioned_docs/version-3.x，对应的版本清单是 website/versions.json（当前为["3.x"]），侧边栏在 website/versioned_sidebars/version-3.x-sidebars.json。
在 website/docusaurus.config.js 中，lastVersion: 'current'且versions.current.label为4.x，因此导航栏右侧会出现版本下拉菜单（docsVersionDropdown），读者可以在 4.x 与 3.x 文档之间切换。这是 H3 4.x 时代文档站的重要结构特征：旧版文档与新版并存，避免用户因 API 变化而迷失。
站点行为由 docusaurus.config.js 决定
website/docusaurus.config.js 是 Docusaurus 站点的总配置文件，几个关键点如下：
- 站点身份：
title: 'H3'、tagline: 'Hexagonal hierarchical geospatial indexing system'、url: 'https://h3geo.org'、baseUrl: '/'、favicon: 'favicon.ico'； - 链接质量保障：
onBrokenLinks: 'throw'、onBrokenAnchors: 'throw'，并且通过markdown.hooks.onBrokenMarkdownLinks: 'throw'让任何失效的内部链接直接导致构建失败——这保证了线上文档中不会出现 404 链接； - 导航与页脚：导航栏包含 About、API、Bindings、Resolutions、版本下拉与 GitHub 链接，Logo 使用 website/static/images/h3Logo-color.svg；页脚提供 Getting Started、Installation、API Reference 与社区入口；
- 文档插件配置：
editUrl会把“编辑此页”链接指向https://github.com/uber/h3/edit/master/website/docs/...，方便读者直接改进文档； - 数学公式：通过
remark-math/rehype-katex插件与外部 KaTeX 样式表支持 LaTeX 公式渲染； - 站内搜索：集成
docusaurus-lunr-search插件，并排除docs/3.x/**路由、禁用版本化索引，确保搜索只覆盖当前版本的文档； - Mapbox Token：
customFields.mapboxAccessToken从环境变量MapboxAccessToken读取——这是交互式地图组件（见下节）的地图瓦片凭证，本地开发时若未设置，地图相关功能可能不显示底图。
交互式演示：Explorer 与可执行代码块
站点并非纯静态文字，还内置了基于 H3 的交互工具：
- 首页（website/src/pages/index.js）渲染了
HomeExplorer组件，它来自 website/src/components/explorer/index.tsx，是一个H3 索引查看器：允许用户输入 H3 单元格索引或有向边索引，在地图上高亮展示，并联动显示单元格详情。代码借助use-location-state把当前输入同步到 URL 的hex与res查询参数，因此可以把某个探索结果作为链接分享出去； - 文档中的可执行代码块通过
@docusaurus/theme-live-codeblock与自定义的 website/src/theme/ReactLiveScope/index.js 实现：后者在ReactLiveScope中注入h3（h3-js 4.x 浏览器版）与h3v3（h3-js 3.x 浏览器版），使读者能在文档页面里直接运行 H3 的 JavaScript API，并直观对比新旧版本行为差异。该文件中的注释还记录了一个工程细节：由于 h3-js 直接引用了浏览器全局对象，构建时需先通过global/window、global/document垫片处理，否则 SSR 构建会失败。
更新文档与内容维护工作流
日常维护 H3 文档的主要步骤可归纳为：
- 修改 website/docs（或 website/versioned_docs/version-3.x）中的 Markdown/MDX 文件；
- 若新增页面，同步更新 website/sidebars.js 的侧边栏结构；
- 本地运行
yarn start预览效果，运行yarn build确认无链接错误、构建通过； - 运行
yarn format统一src/下代码风格； - 提交到
master分支，由 CI 自动测试并部署。
需要注意的是：由于onBrokenLinks等配置为throw，任何指向不存在页面的内部链接、失效的锚点都会让yarn build直接报错，这是文档站对内容质量的一种强制性约束。
部署：GitHub Actions 自动发布到 GitHub Pages
website/README.md 明确说明：网站的部署通过 GitHub Actions 自动完成，只要变更合入master分支就会触发发布。具体实现可以在仓库的 CI 工作流文件中看到。
自动部署工作流
.github/workflows/deploy-website.yml 定义了deploy-website任务：
- 触发器：
push到master分支； - 运行环境：
ubuntu-latest； - 依次执行
actions/checkout拉取代码、actions/setup-node（Node 22）安装环境； - 在
website工作目录下运行yarn --frozen-lockfile（严格按 lockfile 安装，杜绝依赖漂移）与yarn build，并注入密钥MapboxAccessToken（来自仓库 Secrets）供地图组件使用； - 使用
peaceiris/actions-gh-pages把website/build目录推送到gh-pages分支，同时设置cname: h3geo.org，将自定义域名绑定到 GitHub Pages。
因此线上站点的更新链路是：代码推送到 master → CI 构建 → 推送静态产物到 gh-pages → 通过 h3geo.org 提供服务。
网站测试与格式校验
.github/workflows/test-website.yml 提供了配套的质量门禁，触发条件覆盖master、stable-*分支的 push 与 PR：
- 同样以 Node 22 安装依赖并执行
yarn build，验证站点可正常构建（并顺便提交 FOSSA 许可证/依赖扫描报告，若配置了FOSSA_API_KEY）； - 执行
yarn format后运行git diff --exit-code，若 prettier 对src/产生任何格式化差异，CI 即失败——这保证了所有合入的代码风格一致。
也就是说，任何想要改进 H3 文档的提交，在合入master之前都会自动经过“可构建 + 无坏链 + 格式合规”三重校验。
小结
H3 文档网站是一个典型的 Docusaurus 静态文档工程，其核心工作流非常清晰：
- 写内容：编辑 website/docs 下的 Markdown/MDX 文件，并在 website/sidebars.js 中维护导航结构；
- 本地验证：在
website目录执行yarn && yarn start进行开发预览，用yarn build验证生产构建与链接完整性； - 自动上线：将改动合入
master分支，.github/workflows/deploy-website.yml 自动构建并发布到 GitHub Pages，最终呈现在 h3geo.org； - 质量保障：.github/workflows/test-website.yml 在 PR 阶段即拦截构建失败、坏链与格式问题。
对于希望为 H3 贡献文档、搭建本地文档环境，或参考其架构搭建同类地理空间项目文档站的开发者，website 目录本身就是一份可直接复用的完整工程样例。
- GIS
【免费下载链接】h3
Hexagonal hierarchical geospatial indexing system
相关推荐
Webamp 官方文档站（Docusaurus）本地开发、构建与部署完全指南
Webamp 官方文档站（Docusaurus）本地开发、构建与部署完全指南 导读 packages/webamp docs/README.md 记录了 Web
前端音视频BigBlueButton 官方文档站（Docusaurus）本地构建与维护实战指南
BigBlueButton 官方文档站（Docusaurus）本地构建与维护实战指南 BigBlueButton 的在线文档（docs.bigbluebutto
教育音视频后端前端Graphile Build 文档站维护指南：基于 Docusaurus 的构建、部署与版本化全流程
Graphile Build 文档站维护指南：基于 Docusaurus 的构建、部署与版本化全流程 本篇指南面向 Graphile Crystal 仓库的贡献
后端API网关
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
