GIS【免费下载链接】h3Hexagonal hierarchical geospatial indexing system项目地址https://gitcode.com/gh_mirrors/h3/h3点击查看免费下载本指南围绕 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.jswebsite/README.md。除此之外工程通过yarn管理依赖。从 website/package.json 可以看到工程的具体约定包名为h3-website通过volta字段锁定了 Node16.18.1与 yarn1.22.10并通过packageManager声明使用yarn1.22.22——本地开发时建议优先使用相同大版本的工具链避免 lockfile 不兼容核心依赖包括docusaurus/core与docusaurus/preset-classic版本^3.10.1、docusaurus/theme-live-codeblock支持在文档中嵌入可实时执行的代码块与 H3 直接相关的依赖h3-js4.4.0当前版本绑定和h3-jsv3npm: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.mdyarn 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 startdocusaurus start启动开发服务器热更新yarn builddocusaurus build生成生产级静态站点yarn servedocusaurus serve本地预览构建产物yarn swizzledocusaurus swizzle --danger抽取/自定义 Docusaurus 主题组件yarn deploydocusaurus deploy手动发布到 GitHub Pagesyarn cleardocusaurus clear清空本地构建缓存yarn write-translationsdocusaurus write-translations生成多语言翻译所需的 JSON 骨架yarn write-heading-idsdocusaurus write-heading-ids为文档标题补全锚点 IDyarn formatprettier --write src对src下的代码统一格式化yarn format不只是本地习惯它还出现在 CI 的格式检查步骤中见下文“持续集成”一节保证合并进仓库的代码风格一致。文档内容在哪里docs 目录与版本化文档站点正文全部位于 website/docs按主题划分为多个子目录与 website/sidebars.js 中定义的侧边栏结构一一对应Getting StartedREADME站点首页简介、highlights/H3 特性聚合、关联、流量建模、机器学习、索引、comparisons/与 S2、Geohash、Hexbin、行政边界、Placekey 的对比、installation、quickstartConcepts and Guideslibrary/下的术语表、错误码、分辨率表以及 H3 索引结构h3Indexing、cell、directededge、vertex和从 3.x 迁移的指南API Referenceapi/下的indexing、inspection、traversal、hierarchy、regions、uniedge、vertex、miscCommunitycommunity/下的 bindings、libraries、tutorials、applicationsH3 Internalscore-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 TokencustomFields.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中注入h3h3-js 4.x 浏览器版与h3v3h3-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 Pageswebsite/README.md 明确说明网站的部署通过 GitHub Actions 自动完成只要变更合入master分支就会触发发布。具体实现可以在仓库的 CI 工作流文件中看到。自动部署工作流.github/workflows/deploy-website.yml 定义了deploy-website任务触发器push到master分支运行环境ubuntu-latest依次执行actions/checkout拉取代码、actions/setup-nodeNode 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【免费下载链接】h3Hexagonal hierarchical geospatial indexing system项目地址https://gitcode.com/gh_mirrors/h3/h3点击查看免费下载相关推荐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网关上一篇SLM-Lab高级技巧如何优化记忆replay和策略梯度算法下一篇从零开始玩转F1C200s开发板嵌入式Linux实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考