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.
• Notice there is no schema reference folder. 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. This keeps the schema and its documentation permanently in sync.

Every build (CI, PR preview, and production) runs the generate-schema-docs action, which generates Markdown into docs/schema/reference/ from the schema repository's main branch (or a specific schema-ref when triggered via workflow_dispatch, e.g. from an overture-schema release). docs/schema/reference/ is gitignored and never committed 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 — any change here will be overwritten on the next build.

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 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.