Overture Documentation

This repository uses Docusaurus to publish the documentation pages seen at docs.overturemaps.org

Structure

• blog/: Entries for the Overture engineering blog available at docs.overturemaps.org/blog
• community/: The community page that showcases Overture data being used in the wild.
  • community-projects.json - source data for all community project cards
  • og-image-cache.json - cached og:image URLs for entries without an explicit image field (see OG Image Cache below)
• docs/: The main documentation pages available at docs.overturemaps.org/. The sidebar for these pages is manually curated in the sidebars.js file.
• schema/: Source for the schema reference overview page (index.md) and scratch output of the schema doc generator. See below.
• schema_versioned_docs/, schema_versioned_sidebars/, schema_versions.json: committed snapshots of the schema reference for each released schema tag. See below.

Schema Reference (docs.overturemaps.org/schema)

The Overture schema repository OvertureMaps/schema maintains the official Overture schema as Pydantic models, and the reference pages under docs.overturemaps.org/schema are generated directly from those models.

The schema reference is its own versioned Docusaurus docs instance (plugin id schema, config in docusaurus.config.js, sidebar in sidebars-schema.js), separate from the main docs/ instance. Only released schema tags are published; there is no rolling "latest" built from main. The newest tag in schema_versions.json is served at /schema/, older tags at /schema/vX.Y.Z/, and a version dropdown appears in the navbar on schema pages only.

Snapshots are generated once per tag and committed under schema_versioned_docs/version-vX.Y.Z/. Builds do not call the schema generator, so a production deploy only ever changes the schema pages when a new snapshot lands here.

If you spot a typo or error under docs.overturemaps.org/schema, it is not fixable in this repository. Open an issue or PR against the docstrings/models in OvertureMaps/schema instead; the fix appears in the next release's snapshot. Re-snapshotting an existing tag is possible (delete its three artifacts and re-run the script below) but pointless unless the tag itself moved.

The overview page (schema/index.md) is copied into each snapshot when it's created. Edits to it need to be applied to the index.md in each schema_versioned_docs/version-*/ too.

Adding a schema version

Run this after a vX.Y.Z tag is published in OvertureMaps/schema. It needs git, uv, and npm install already done.

npm run add-schema-version -- v2.0.0

The script (scripts/add-schema-version.mjs) clones the schema repo at that tag, runs its overture-codegen into schema/reference/, then runs docusaurus docs:version:schema <tag>, which writes:

• schema_versioned_docs/version-<tag>/ (with links into the schema repo pinned to the tag)
• schema_versioned_sidebars/version-<tag>-sidebars.json
• an entry in schema_versions.json (kept sorted newest-first; the first entry is what /schema/ serves)

Commit those three and open a PR. schema/reference/ is cleaned up afterwards.

Only tags that ship the overture-schema-codegen package (v1.17.0 and later) can be added; earlier releases were JSON Schema and have no generator. The script refuses tags that don't match vX.Y.Z or are already in schema_versions.json.

Schema PR previews

The schema repo's PR preview workflow checks out this repo, generates Markdown from the PR branch into schema/reference/, and builds with SCHEMA_PREVIEW=true. In that mode the schema instance builds only the current version from schema/reference/ at /schema/; committed snapshots, the version dropdown, blog, and community pages are skipped.

Developing

Docusaurus requires node. First, install the required packages:

npm install

Then, start the local server:

npm start

Now navigate to http://localhost:3000 to see the live preview.

Available Commands

• npm start - Start the development server
• npm run build - Build the production site (also shows locale/translation warnings and broken link checks)
• npm run serve - Serve the built site locally
• npm run deploy - Deploy the site
• npm run fetch-og - Fetch and cache og:image metadata for community project entries (see OG Image Cache below)
• npm run add-schema-version -- vX.Y.Z - Snapshot the schema reference for a released schema tag (see Adding a schema version above)
• npm run swizzle - Customize Docusaurus components by "ejecting" them for modification
• npm run write-translations - Generate translation files for internationalization
• npm run write-heading-ids - Auto-generate heading IDs for better linking

OG Image Cache

The community page displays project cards with images. Each entry in community/community-projects.json can include an optional "image" field. For entries without one, the site falls back to a cached og:image fetched from the project's URL.

The cache lives in community/og-image-cache.json and is committed to the repository so CI builds never make external HTTP requests.

When to run it: after adding or updating entries in community-projects.json.

npm run fetch-og

The script (scripts/fetch-og-images.mjs):

1. Skips entries that already have an explicit "image" field
2. Re-validates any previously cached non-empty URLs via a HEAD request (Content-Type: image/*) and clears invalid ones
3. Fetches the HTML for uncached entries, extracts og:image, and validates the URL before writing it to the cache
4. Is idempotent - safe to re-run at any time

Cards with no image (neither explicit nor cached) display a branded gradient placeholder.

LLM-Friendly Content

Each production build generates llmstxt.org-standard files for use with LLMs and AI tools:

File	URL	Contents
llms.txt	docs.overturemaps.org/llms.txt	Index of all docs and blog posts with links
llms-full.txt	docs.overturemaps.org/llms-full.txt	Full content of all docs and blog posts
llms-schema.txt	docs.overturemaps.org/llms-schema.txt	Full schema reference only (useful for data model questions)

These are generated by docusaurus-plugin-llms and configured in docusaurus.config.js.