Skip to main content
The docs site is driven by Mintlify from the sitectl-docs repository. Mintlify reads:
  • docs.json for navigation and site settings
  • index.mdx for the homepage
  • .mdx files under the repository root for all other pages

​
Local development

Mintlify’s local dev startup command is mint dev, but Mintlify does not support Node 25+. This repo avoids that issue by running Mintlify in a Node 22 Docker container. The preview and validation targets use the same exact Mint CLI version from MINT_VERSION in the Makefile:
The docs server binds to port 3000 by default. Override with:
If you already have a supported LTS Node version installed locally:

​
Command reference snippets

Command reference blocks (the auto-generated usage and flags tables) live in snippets/commands/ and are generated from the Go source. Do not edit them by hand because they will be overwritten on the next run. Regeneration removes obsolete .mdx files that carry the auto-generated header while preserving manually maintained files. To regenerate after changing a command’s flags or description:
Pull requests run make docs-snippets-check, which regenerates these files from the exact core and plugin commits recorded in scripts/snippet-dependencies.json and fails when the result differs from the committed snippets. The dependency check requires an exact manifest/module/replace set and verifies that every recorded stable release tag resolves to its recorded commit. The same required workflow runs the pinned Mintlify CLI through make docs-check to validate the strict documentation build and internal links. When one command change spans repositories, publish core first, then any plugin dependency, then the dependent plugins, and open or refresh the docs pull request last. Update each manifest version and ref only after the stable tag exists and resolves to that exact commit. Hosted docs CI checks those immutable commits rather than moving default branches. Do not hand-edit generated snippets to make documentation run ahead of the command binaries they describe. This runs scripts/gen-docs-snippets/main.go, which imports the core sitectl command tree plus every plugin in the active v1 compatibility set: sitectl-isle, sitectl-drupal, sitectl-archivesspace, sitectl-ojs, sitectl-omeka-classic, sitectl-omeka-s, sitectl-wp, and sitectl-libops. It renders each command to an .mdx snippet file. The generator is a self-contained Go module: it resolves sibling plugin repos through the require/replace directives in scripts/gen-docs-snippets/go.mod. make docs-snippets sets GOWORK=off, runs from inside that module, and passes the docs root as the output base, so an ambient workspace cannot substitute another dependency graph. To add a plugin to the generated reference, update all of these contracts together:
  1. Add the repository key, module version, stable tag commit, and checkout directory to scripts/snippet-dependencies.json and to the checker’s exact expected_keys set.
  2. Add matching direct require and local replace directives to scripts/gen-docs-snippets/go.mod.
  3. Add the plugin import and generator registration to scripts/gen-docs-snippets/main.go.
  4. Add the exact-SHA checkout step to .github/workflows/docs-check.yaml; dependency linking is derived from the manifest.
The checker rejects missing or extra sitectl modules, indirect requirements, mismatched local replace paths, unpublished tags, and tags that do not resolve to the recorded commit. When a plugin is temporarily outside the active compatibility set, do not leave its module in the active generator and rely on Go’s minimum-version selection to make it compile. Remove it from the active manifest, module, hosted checkout graph, and generated command reference until a compatible stable release exists. The generator skips hidden commands (those starting with __) and thin plugin-passthrough wrappers (commands that disable flag parsing and only forward arguments, such as sitectl wp cli or sitectl ojs tool). Those passthrough commands are documented in hand-written prose instead.

​
Tooltip snippets

Reusable tooltip definitions for technical terms live in snippets/. Import and use them in any page:
Use these consistently across home-tab pages so readers who hover over a term see a definition. The contributing tab can use raw technical language without tooltips. When adding a new term that appears in multiple pages and may be unfamiliar to a non-sysadmin audience, create a tooltip snippet file rather than duplicating inline tooltip markup.

​
Making docs changes

When you update the docs:
  • preserve the existing nav structure in docs.json and only add to it when needed
  • use MDX for new pages
  • keep contributor and operator guidance in the docs site instead of a CONTRIBUTING.md file
  • home-tab pages (the operator-facing docs) should avoid jargon and use tooltip snippets for acronyms
  • contributing-tab pages can be fully technical

​
Deployment

Docs deploy through the Mintlify GitHub App connected to this repository. There is no GitHub Pages workflow to maintain.