docs.earthscope.org

Source for docs.earthscope.org, EarthScope's technical documentation hub. The site is built using MyST and hosts the top-level landing pages and links out to the docs for individual tools (Services, Data, GeoLab), which live in their own repositories.

Repo layout

• index.md, user_account.md, citation.md — page content for this site.
• myst.yml — project config (title, copyright, extended shared configs).
• es_config/earthscope.yml — shared MyST config (theme, nav bar, logos) extended by this and other EarthScope docs repos.
• es_config/topleveltoc.yml — shared top-level table of contents, extended by this repo and by other top-level repos that opt in (see "Shared top-level ToC" below).
• es_config/search-widget.mjs — custom search button/modal backed by a Google Programmable Search Engine.
• scripts/build-docs.sh — central build script, also fetched and run directly by the other EarthScope docs repos' Netlify builds.
• scripts/fix-sitemap.mjs — post-build fixup for sitemap.xml/robots.txt (myst-theme's static export hardcodes localhost as the origin) and merges in URLs from the other projects listed in netlify.toml.
• netlify.toml — Netlify build settings and the redirects that stitch the other EarthScope docs sites under docs.earthscope.org/<path>.
• plugins/fanout/ — local Netlify build plugin that rebuilds the other EarthScope docs sites when the files they share with this repo change.

Local testing

Prerequisites: Node.js (v24 to match Netlify, see netlify.toml).

Install mystmd (pinned version comes from scripts/build-docs.sh):

npm install -g mystmd@~1.11.0

Start a live-reloading local server:

myst start

This serves the site at http://localhost:3000 and rebuilds pages as you edit them.

To reproduce the actual production build (static HTML export, plus the sitemap/robots.txt fixups):

myst build --html
node scripts/fix-sitemap.mjs

Output goes to _build/html. Note that fix-sitemap.mjs fetches the sitemap/robots.txt of every other project referenced in netlify.toml, so it requires network access and those sites to be reachable.

Shared top-level ToC

es_config/topleveltoc.yml holds a fixed project.toc (index.md, user_account.md (hidden), then links to User Account and Open Data on AWS). This repo extends it by local path; another top-level repo opts in by extending it by URL, after earthscope.yml:

extends:
  - https://raw.githubusercontent.com/EarthScope/docs.earthscope.org/main/es_config/earthscope.yml
  - https://raw.githubusercontent.com/EarthScope/docs.earthscope.org/main/es_config/topleveltoc.yml

Sub-sites (CLI, SDK, GeoLab, ...) don't extend it and keep their own ToC. Rules for a repo that opts in:

• It must not define project.toc: MyST uses an extended ToC only when the site has none, and does not merge them.
• It must have an index.md; the first ToC entry has to be a file.
• file: paths resolve against the repo doing the build, so user_account.md is missing there. MyST logs an error-level warning for it (the build still succeeds) and leaves the entry out. That file entry is hidden; the sidebar link comes from the separate url: entry for User Account, which works in every repo.
• Only files listed in the ToC are built, so any other page in that repo is not part of its site.

Local dev on the search widget

es_config/earthscope.yml points navbar_end at the raw GitHub URL for es_config/navbar_end_external.md on main, so local edits to that file (or to search-widget.mjs, which it references) won't show up in myst start until pushed. To test search-widget changes locally, comment out that line in es_config/earthscope.yml and uncomment the one below it that points at the local es_config/navbar_end.md instead.

Deployment

Netlify builds this repo (and the other EarthScope docs repos) by running scripts/build-docs.sh, which installs the pinned mystmd version, runs myst build --html, and — for the root project only — runs scripts/fix-sitemap.mjs. See netlify.toml for build settings and redirects.

Propagating shared config to the other docs sites

The other repos pull es_config/ over raw.githubusercontent.com and curl scripts/build-docs.sh during their own builds, so changing either one here leaves them stale until they rebuild. The plugins/fanout build plugin closes that gap: after a successful production deploy, if either path changed since the last build, it POSTs to each subsite's Netlify build hook.

The baseline is the last successful production deploy, looked up through the Netlify API with the build's own token, so no extra variable is needed. This holds up for multi-commit pushes, failed builds in between, and builds without a cache. If the lookup fails, the plugin falls back to the build cache, or to the built commit's parent when there is no cache (which can miss an earlier commit in a multi-commit push); the build log says which baseline was used. If the git comparison itself fails, the plugin triggers anyway.

Hook URLs are read from build-scoped environment variables, one per subsite, named SUBSITE_HOOK_<NAME> (for example SUBSITE_HOOK_GEOLAB). Set them under Project configuration → Environment variables, and mark them secret. With none set, the plugin does nothing. Setting DRY_RUN to any non-empty value logs which subsites would be triggered without firing the hooks.