[CHORE] Add SCHEMA_PREVIEW build mode + misc. fixes for publishing

.github/dependabot.yml

@@ -2,6 +2,18 @@
 version: 2
 updates:
 
+  # Maintain npm dependencies
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "bot"
+    commit-message:
+      prefix: "[CHORE](deps)"
+      include: "scope"
+
   # Maintain GitHub Actions dependencies
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/production_deploy_documentation.yml

@@ -28,10 +28,13 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: '24'
+          node-version-file: package.json
+
+      - name: Configure sustainable npm
+        uses: lowlydba/sustainable-npm@ed089bd92235c2af803a951fba2bd42c59fbcd73 # v2.0.0
 
       - name: Install NPM dependencies
-        run: npm install --prefer-dedupe
+        run: npm ci --prefer-dedupe
 
       - name: Build Docusaurus Pages 🔧
         run: npm run build

.github/workflows/staging_deploy.yaml

@@ -1,84 +1,172 @@
 ---
 name: Staging Deploy
-run-name: Publish docs to staging website (for PR)
+run-name: Publish docs to staging website
 
 on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: staging-deploy-${{ github.event.number }}
+  cancel-in-progress: true
+
 permissions:
   id-token: write
   contents: read
   pull-requests: write
 
+env:
+  DOCS_PATH: docs
+  PREVIEW_PATH: /${{ github.event.repository.name }}/pr/${{ github.event.number }}
+  PREVIEW_PATH_NO_AUTOGEN: /${{ github.event.repository.name }}/pr/${{ github.event.number }}-no-autogen
+  STAGING_URL: https://staging.overturemaps.org
+  SCHEMA_PREVIEW: false # Set to true to only publish Schema reference docs
+  AWS_ROLE_ARN: arn:aws:iam::763944545891:role/pages-staging-oidc-overturemaps
+  AWS_REGION: us-west-2
+
 jobs:
-  build:
-    name: Build
+  check-fork:
+    name: Check fork
+    runs-on: ubuntu-slim
+    steps:
+      - name: Staging deploy is not supported for fork PRs
+        if: github.event.pull_request.head.repo.full_name != github.repository
+        run: |
+          echo "::warning title=Staging deploy not supported for fork PRs::Staging previews are only available for PRs from branches within this repository, not forks. Please open your PR from a branch in OvertureMaps/docs instead."
+
+  build-auto-gen:
+    name: Build (auto-gen schema)
+    if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
+    needs: check-fork
+    outputs:
+      schema-sha: ${{ steps.schema-docs.outputs.schema-sha }}
+      schema-ref: ${{ steps.schema-docs.outputs.schema-ref }}
     steps:
       - name: Check out the main docs repo repository and build.
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: '24'
+          node-version-file: 'package.json'
+
+      - uses: lowlydba/sustainable-npm@v2
 
-      - name: Install NPM dependencies
-        run: npm ci --omit=dev
+      - run: npm ci --omit=dev
+
+      - name: Generate schema markdown docs
+        id: schema-docs
+        uses: OvertureMaps/workflows/.github/actions/generate-schema-docs@main
+        with:
+          output-dir: ${{ github.workspace }}/docs/schema/reference
+          schema-ref: 'dev' # Temporary until we feel confident in the generated schema sans human review, then should be 'main'
 
       - name: Build Docusaurus website
-        env:
-          DOCUSAURUS_URL: https://staging.overturemaps.org/
-          DOCUSAURUS_BASE_URL: /${{ github.event.repository.name }}/pr/${{ github.event.number }}/
         run: npm run build
+        env:
+          DOCUSAURUS_URL: ${{ env.STAGING_URL }}/
+          DOCUSAURUS_BASE_URL: ${{ env.PREVIEW_PATH }}/
+          SCHEMA_PREVIEW: ${{ env.SCHEMA_PREVIEW }}
 
       - name: Upload docs build as an artifact 📦
         uses: actions/upload-artifact@v7
         with:
           path: build
           name: build-artifact
 
+  build-repo-schema:
+    # Branch ruleset set to this job name to require this status check
+    name: Build
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    needs: check-fork
+    steps:
+      - name: Check out the main docs repo repository and build.
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: 'package.json'
+
+      - uses: lowlydba/sustainable-npm@v2
+
+      - run: npm ci --omit=dev
+
+      - name: Build Docusaurus website (using existing /schema/reference files)
+        run: npm run build
+        env:
+          DOCUSAURUS_URL: ${{ env.STAGING_URL }}/
+          DOCUSAURUS_BASE_URL: ${{ env.PREVIEW_PATH_NO_AUTOGEN }}/
+          SCHEMA_PREVIEW: ${{ env.SCHEMA_PREVIEW }}
+
+      - name: Upload docs build as an artifact 📦
+        uses: actions/upload-artifact@v7
+        with:
+          path: build
+          name: build-artifact-no-autogen
+
   deploy:
     name: Deploy
-    runs-on: ubuntu-latest
-    needs: build
+    runs-on: ubuntu-slim
+    needs: [check-fork, build-auto-gen, build-repo-schema]
     environment:
       name: staging
-      url: https://staging.overturemaps.org/${{ github.event.repository.name }}/pr/${{ github.event.number }}/index.html
+      url: ${{ env.STAGING_URL }}${{ env.PREVIEW_PATH }}/index.html
 
     steps:
       - name: Configure AWS credentials 🔐
         uses: aws-actions/configure-aws-credentials@v6
         with:
-          role-to-assume: arn:aws:iam::763944545891:role/pages-staging-oidc-overturemaps
-          aws-region: us-west-2
+          role-to-assume: ${{ env.AWS_ROLE_ARN }}
+          aws-region: ${{ env.AWS_REGION }}
 
-      - name: Download artifacts 📥
+      - name: Download auto-gen artifact 📥
         uses: actions/download-artifact@v8
         with:
           name: build-artifact
-          path: build
+          path: build-autogen
+
+      - name: Download repo schema artifact 📥
+        uses: actions/download-artifact@v8
+        with:
+          name: build-artifact-no-autogen
+          path: build-no-autogen
 
       - name: Copy to S3
         run: |
-          aws s3 sync --delete build s3://overture-managed-staging-usw2/gh-pages/${{ github.event.repository.name }}/pr/${{ github.event.number }}/
+          aws s3 sync --delete --quiet build-autogen s3://overture-managed-staging-usw2/gh-pages${{ env.PREVIEW_PATH }}/
+          aws s3 sync --delete --quiet build-no-autogen s3://overture-managed-staging-usw2/gh-pages${{ env.PREVIEW_PATH_NO_AUTOGEN }}/
+
       - name: Bust the Cache
-        run: aws cloudfront create-invalidation --distribution-id E1KP2IN0H2RGGT --paths "/${{ github.event.repository.name }}/pr/${{ github.event.number }}/*"
+        run: |
+          aws cloudfront create-invalidation --distribution-id E1KP2IN0H2RGGT --paths "${{ env.PREVIEW_PATH }}/*" "${{ env.PREVIEW_PATH_NO_AUTOGEN }}/*"
 
-      - name: Get deploy timestamp
-        id: timestamp
-        run: echo "time=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" >> $GITHUB_OUTPUT
+      - name: Gather metadata for PR comment
+        id: deploy-metadata
+        run: |
+          echo "time=$(date -u +'%b %d, %Y %H:%M UTC')" >> $GITHUB_OUTPUT
+          echo "short-sha=$(echo '${{ github.event.pull_request.head.sha }}' | cut -c1-7)" >> $GITHUB_OUTPUT
+          echo "schema-ref-short=$(echo '${{ needs.build-auto-gen.outputs.schema-ref }}' | sed 's|refs/heads/||;s|refs/tags/||')" >> $GITHUB_OUTPUT
+          echo "schema-short-sha=$(echo '${{ needs.build-auto-gen.outputs.schema-sha }}' | cut -c1-7)" >> $GITHUB_OUTPUT
 
       - name: Comment on PR
-        uses: marocchino/sticky-pull-request-comment@v3
+        uses: marocchino/sticky-pull-request-comment@70d2764d1a7d5d9560b100cbea0077fc8f633987 # v3.0.2
         with:
           message: |
-            ## 🚀 Overture Maps docs branch preview deployed!
+            ## 🗺️ OMF Docs previews are live!
+
+            |                         |                                                                      |
+            |-------------------------|----------------------------------------------------------------------|
+            | 🆕 **Auto-gen schema site (beta)**  | ${{ env.STAGING_URL }}${{ env.PREVIEW_PATH }}/index.html           |
+            | 🗂️ **Auto-gen schema ref** | [${{ steps.deploy-metadata.outputs.schema-ref-short }}@${{ steps.deploy-metadata.outputs.schema-short-sha }}](https://github.com/OvertureMaps/schema/commit/${{ needs.build-auto-gen.outputs.schema-sha }}) |
+            | 🌍 **Repo schema site**      | ${{ env.STAGING_URL }}${{ env.PREVIEW_PATH_NO_AUTOGEN }}/index.html |
+            | 🕐 **Updated**          | ${{ steps.deploy-metadata.outputs.time }}                            |
+            | 📝 **Commit**           | [${{ steps.deploy-metadata.outputs.short-sha }}](${{ github.server_url }}/${{ github.repository }}/commit/${{ github.event.pull_request.head.sha }}) |
 
-            You can review your changes at https://staging.overturemaps.org/${{ github.event.repository.name }}/pr/${{ github.event.number }}/index.html
+            Auto-gen schema site is now available. This is an early preview of a future workflow where we will automatically generate and publish reference docs for the Overture Maps Format schema with every change to the schema repo.
+            The auto-gen schema site may contain incomplete or inaccurate information as we are still refining the generation process, so please compare against the repo schema site and refer to the linked commit for the most up-to-date source of truth.
 
-            ---
-            <sub>♻️ Last refreshed: ${{ steps.timestamp.outputs.time }}</sub>
+            > [!NOTE]
+            > ♻️ This preview updates automatically with each push to this PR.

.github/workflows/staging_deploy_cleanup.yaml

@@ -0,0 +1,40 @@
+---
+name: Staging Deploy Cleanup
+run-name: ♻️ Clean up staging preview for PR #${{ github.event.number }}
+
+on:
+  pull_request:
+    types: [closed]
+
+permissions:
+  contents: read
+
+jobs:
+  cleanup:
+    name: Cleanup
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-slim
+    permissions:
+      id-token: write
+    env:
+      AWS_ROLE_ARN: arn:aws:iam::763944545891:role/pages-staging-oidc-overturemaps
+      AWS_REGION: us-west-2
+
+    steps:
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: ${{ env.AWS_ROLE_ARN }}
+          aws-region: ${{ env.AWS_REGION }}
+
+      # No flags to ignore "not found" errors, so we use "|| true" to prevent failure if the path doesn't exist
+      - name: Delete from S3
+        run: |
+          aws s3 rm --recursive \
+            s3://overture-managed-staging-usw2/gh-pages/${{ github.event.repository.name }}/pr/${{ github.event.number }}/ || true
+
+      - name: Bust the cache
+        run: |
+          aws cloudfront create-invalidation \
+            --distribution-id E1KP2IN0H2RGGT \
+            --paths "/${{ github.event.repository.name }}/pr/${{ github.event.number }}/*" || true

blog/2025-05-21-release-notes.mdx

@@ -48,7 +48,7 @@ s3://overturemaps-us-west-2/bridgefiles/2025-05-21.0
 
 ## GERS IDs will become UUIDs in June
 
-In next month's release (late June), Overture is standardizing the [`id` property](/schema/#top-level-properties) across all themes by adopting [UUIDs](https://www.rfc-editor.org/rfc/rfc9562.html), stored as strings.
+In next month's release (late June), Overture is standardizing the [`id` property](/schema/) across all themes by adopting [UUIDs](https://www.rfc-editor.org/rfc/rfc9562.html), stored as strings.
 
 Currently the structure of our IDs varies slightly across datasets, with some themes embedding metadata (e.g. [H3](https://h3geo.org/)) in the `id` property. The new UUIDs will be randomly-generated identifiers with no encoded information. Moving to UUIDs enables consistent ID generation and registration across our data pipelines, which is necessary for the successful implementation of [GERS](/gers).
 

blog/2025-06-25-release-notes.mdx

@@ -66,7 +66,7 @@ You can access the datasets by following the process outlined [here](/getting-da
 
 ## What's new? Big changes to GERS.
 
-In this release, Overture has standardized the [`id` property](/schema/#top-level-properties) across all themes by adopting [UUIDs](https://www.rfc-editor.org/rfc/rfc9562.html), stored as strings. This is a **one-time** breaking change for our ID system. For this release only, we are offering Parquet files, partioned by `theme` and `type` that map the old May IDs to the new June UUIDs. You can find that file here: `s3://overturemaps-extras-us-west-2/june_to_may_id_mapping/`.
+In this release, Overture has standardized the [`id` property](/schema/) across all themes by adopting [UUIDs](https://www.rfc-editor.org/rfc/rfc9562.html), stored as strings. This is a **one-time** breaking change for our ID system. For this release only, we are offering Parquet files, partioned by `theme` and `type` that map the old May IDs to the new June UUIDs. You can find that file here: `s3://overturemaps-extras-us-west-2/june_to_may_id_mapping/`.
 
 Overture is now producing [bridge files](https://docs.overturemaps.org/gers/bridge-files/) with each release. You can find the latest bridge files here, partitioned by `dataset`, `theme`, and `type`:
 

docusaurus.config.js

@@ -9,6 +9,12 @@ const darkCodeTheme = themes.nightOwl;
 const defaultUrl = 'https://docs.overturemaps.org';
 const defaultBaseUrl = '/';
 
+// SCHEMA_PREVIEW is set by the schema repo's CI when building a PR preview of the
+// schema reference docs (see OvertureMaps/schema/.github/workflows/schema-pr-preview.yml).
+// When true, only the schema reference section is built — blog, community pages, and
+// navbar items unrelated to the schema are excluded to keep the preview fast and focused.
+const isSchemaPreview = process.env.SCHEMA_PREVIEW === 'true';
+
 function getFromEnvironment(variableName, defaultValue) {
   const environmentValue = process.env[variableName];
   return environmentValue ? environmentValue : defaultValue;
@@ -67,6 +73,8 @@ const config = {
   projectName: 'docs', // Usually your repo name.
 
   onBrokenLinks: 'throw',
+  onBrokenAnchors: 'throw',
+  onDuplicateRoutes: 'throw',
 
   markdown: {
     hooks: {
@@ -86,17 +94,19 @@ const config = {
 
   themes: [],
 
-  plugins: [
-    [
-      '@docusaurus/plugin-content-pages',
-      {
-        id: 'community',
-        path: './community',
-        routeBasePath: 'community',
-        showLastUpdateTime: true,
-      },
-    ],
-  ],
+  plugins: isSchemaPreview
+    ? []
+    : [
+        [
+          '@docusaurus/plugin-content-pages',
+          {
+            id: 'community',
+            path: './community',
+            routeBasePath: 'community',
+            showLastUpdateTime: true,
+          },
+        ],
+      ],
 
   presets: [
     [
@@ -109,12 +119,14 @@ const config = {
           showLastUpdateTime: true,
           breadcrumbs: false,  
         },
-        blog: {
-          blogTitle: 'Overture Maps Engineering Blog',
-          blogDescription: 'Building Overture Maps',
-          blogSidebarTitle: 'Posts from the Overture Maps engineering team',
-          blogSidebarCount: 20,
-        },
+        blog: isSchemaPreview
+          ? false
+          : {
+              blogTitle: 'Overture Maps Engineering Blog',
+              blogDescription: 'Building Overture Maps',
+              blogSidebarTitle: 'Posts from the Overture Maps engineering team',
+              blogSidebarCount: 20,
+            },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
         },
@@ -151,16 +163,20 @@ const config = {
             position: 'left',
             label: 'Docs',
           },
-          {
-            to: 'blog',
-            label: 'Blog',
-            position: 'left',
-          },
-          {
-            to: 'community',
-            label: 'Community',
-            position: 'left',
-          },
+          ...(!isSchemaPreview
+            ? [
+                {
+                  to: 'blog',
+                  label: 'Blog',
+                  position: 'left',
+                },
+                {
+                  to: 'community',
+                  label: 'Community',
+                  position: 'left',
+                },
+              ]
+            : []),
           {
             to: 'https://github.com/OvertureMaps/docs',
             position: 'right',