Skip to content

Documentation site

The public documentation site is built from the repository's existing Markdown. The model and conversion profiles remain drafts. NMDC analyses describe NMDC records, not universal requirements for every producer.

Build and preview

just docs-build
just docs-serve 8765

Preview at http://127.0.0.1:8765/feature-table-corpus/. The server binds to loopback. Use another port if needed. Add new public documentation files to Git before building: the staging step includes only tracked/staged files, using their current working-tree contents. Re-run after editing; preview serves the staged copy. just docs-check checks an already built site's local links and fragments.

MkDocs with Material supplies navigation, search, tables, code blocks, and Mermaid rendering without relocating prose. requirements-docs.txt pins the direct dependencies. Mermaid's browser renderer is loaded by the theme; it requires network access. The Markdown diagram source remains available in the repository.

One maintained source

mkdocs.yml defines reading paths for evidence, draft contracts, executable examples, and explicitly NMDC-specific reports. scripts/prepare_docs.py stages allowed tracked files from docs/, model/, analyses/, corpus/, scripts/, and tests/, plus named root files, under gitignored local/site-src/. Source/data/code artifacts remain downloadable. Directory indexes are generated navigation, not a second maintained prose tree. The built site goes in local/site/.

Files under local/, untracked downloads, dotfiles, private research notes, database binaries, and external symlinks are excluded. The build does not scan Desktop notes or retrieve participant traces. Adding new public roots or file types requires changing the explicit publication allowlist.

Checks and deployment

Every PR runs a strict build and checks every built local HTML link, fragment, and resource reference. External URL availability is outside this offline check. PR builds produce a downloadable Actions preview artifact and have no deployment permissions. Successful main-branch builds upload a Pages artifact; a separate deployment job alone receives pages: write and id-token: write, using the github-pages environment. Manual dispatch also deploys only from main. Runs for the same PR or branch never overlap: main builds queue, and a newer PR push cancels the older PR build. GitHub does not guarantee queue order, so a main build checks out main's head when it starts instead of its triggering commit. The last run to start therefore always publishes the latest main.

The repository Pages setting must use GitHub Actions. The workflow becomes active when this change reaches main; a PR preview does not establish that the public URL has deployed. If deployment fails, inspect the documentation workflow and Pages environment/settings before claiming publication succeeded.