> ## Documentation Index > Fetch the complete documentation index at: https://sitectl.libops.io/llms.txt > Use this file to discover all available pages before exploring further. # Documentation > How to edit, preview, and organize the Mintlify documentation in the sitectl-docs repository. export const TUI = () => TUI ; The docs site is driven by [Mintlify](https://www.mintlify.com/docs) from the [sitectl-docs](https://github.com/libops/sitectl-docs) repository. Mintlify reads: * [docs.json](https://github.com/libops/sitectl-docs/blob/main/docs.json) for navigation and site settings * [index.mdx](https://github.com/libops/sitectl-docs/blob/main/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: ```bash theme={null} make docs ``` The docs server binds to port `3000` by default. Override with: ```bash theme={null} make docs DOCS_PORT=3333 ``` If you already have a supported LTS Node version installed locally: ```bash theme={null} make docs-host ``` ## 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: ```bash theme={null} make docs-snippets ``` 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: ```mdx theme={null} import { SSH } from "/snippets/ssh-tooltip.mdx"; import { TUI } from "/snippets/tui-tooltip.mdx"; import { Compose } from "/snippets/compose-tooltip.mdx"; import { YAML } from "/snippets/yaml-tooltip.mdx"; import { CLI } from "/snippets/cli-tooltip.mdx"; ``` 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.