Contributing to the field guide
The public documentation lives in site/. Internal specifications and design
notes remain in docs/.
Local preview
./build.sh docs:tools
./build.sh docs:serveThe tools target downloads pinned, checksum-verified Hugo and Hextra releases to the repository cache. It does not install system-wide tools. Python 3.9 or newer and Go are required.
Build and verify
./build.sh docs:check
./build.sh docs:buildThe build generates illustrations and the property reference before running Hugo.
The check also runs the executable example tests, validates article topics, and
checks local links in the built site. Output goes to dist/site/.
Executable examples
Put complete examples in site/examples/. The example shortcode includes the
source and its generated diagram. Add assertions about the behavior being taught
to internal/docexamples/examples_test.go; test semantic results rather than
SVG snapshots. Update examples in the same change as the behavior they explain.
Topics
Every article declares topics in front matter. Use the controlled vocabulary in
site/data/topics.json. Topic browse pages are disabled initially, while the
metadata is validated on every documentation build.
Markdown edits reload during local preview. After changing an MGL example, rerun
./build.sh docs:build to regenerate its illustration.
Editions
The site uses Hugo’s native versions and sites.matrix mounts. Every minor
release line has a permanent URL such as /v0.5/; its selector label is 0.5.x.
Each patch advances that line to the documentation frozen with the new patch.
The site root redirects to the current stable line, or /dev/ before the first
release. Development resources are regenerated from the checkout.
The selector offers the current line, the previous two minor lines, and dev.
Older editions remain accessible at their original URLs and through the archive
listing. They display an unsupported notice and a link to the current edition.
Only current stable pages are indexable and included in the search sitemap.
Other editions use noindex; search engines must be allowed to crawl those
pages to read that directive. On-site search stays within the selected edition.
Prepare a release snapshot
Before committing and tagging a release, run:
./build.sh docs:tools
./build.sh docs:freeze -docs-release v0.5.0Commit docs/site-snapshot/ with the release. It contains the documentation content, generated property
reference, rendered diagrams, original example sources, and release identity.
Do not commit the built HTML site. Subsequent site builds import these frozen
resources directly; they never run Meridian against a released edition.
After the tag exists, register or advance its minor line in site/hugo.toml:
[versions.'v0.5']
weight = 10
[params.docReleases]
"v0.5" = "v0.5.0"Add the mapping to the existing table rather than declaring that table twice.
Keep entries for archived lines. The snapshot is outside the nested site Go module so it is included in the
root module archive downloaded from release tags. The build uses the explicit list to construct
pinned imports of github.com/meridian-graph/meridian, ignores the imported
configuration, and mounts each tag’s content and frozen resources separately.
Missing snapshots or mismatched release identities fail the site build. Advance
the mapping for each patch; adding a new minor line automatically moves the
oldest selectable line into the archive. Revisit retention before version 1.0.
Crawler controls cannot guarantee that AI systems forget previously collected
content. Titles and visible notices identify archived and unreleased editions.
The build generates /robots.txt at https://meridian-graph.dev/, allowing
search engines to fetch every edition’s indexing directives. GPTBot and
OAI-SearchBot are restricted to the current stable edition; development,
noncurrent editions, and their generated resources are excluded for those bots.
These provider-specific rules do not prevent a person or a user-directed tool
from visiting an archived page.
Hextra v0.13.0 is pinned. Its search templates have small local overrides to include the native version name in generated resource paths. Review those overrides when upgrading the theme.
GitHub Pages
The Pages workflow checks documentation on pull requests and publishes from
dev. Every deployment builds all configured editions together. In repository settings, select GitHub Actions as the Pages source.
The site is built for https://meridian-graph.dev/. Set that custom domain in
Pages settings, configure its DNS records for GitHub Pages, and enable HTTPS.
Custom Actions deployments use the repository’s domain setting; a CNAME file
in the output is not required.
On a push to dev, the workflow checks out the code, installs the build tools,
generates development resources, imports configured frozen release snapshots,
and validates the combined site. It uploads only dist/site/ as a Pages artifact.
A second job deploys that artifact to the github-pages environment using the
workflow’s short-lived GitHub token. No personal token or publishing branch is
needed. Pull requests run the build checks without deployment. The workflow also
supports manual runs on dev. If the environment has branch restrictions, allow
dev to deploy. Until a stable release is registered, / redirects to /dev/
and all documentation remains marked unreleased and excluded from indexing.