Skip to content
Development · unreleased
Edition: dev
Documentation archive
Contributing to the field guide

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:serve

The 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:build

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

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