Publishing the docs

The documentation site uses Jekyll and Just the Docs in dark mode. It is deployed to GitHub Pages by the Docs workflow. Its dependencies are separate from the Rails engine’s bundle.

Edit and export

Canonical Markdown lives in the TechWright vault at _vault/products/admin_suite/docs/. Edit those sources, not the generated files under site/generated/. Public pages are explicitly selected by site/publication.yml; internal plans, reports, and the vault index are excluded.

Commit the canonical source changes in the vault first. From the AdminSuite repository, export that immutable commit with Ruby 3.4 available:

bin/export-docs --source /path/to/_vault/products/admin_suite/docs --revision VAULT_COMMIT
bin/export-docs --source /path/to/_vault/products/admin_suite/docs --check

--check uses the exported revision by default and fails if the working sources or generated output differ. The export records the vault commit, source root, source and output SHA-256 hashes, exporter hash, and allowlist hash. It removes vault front matter and explicitly marked private sections, converts links to published routes, and rejects unresolved vault links. Add page-specific private sections using paired HTML comments named public-docs:omit:start and public-docs:omit:end.

Commit the generated snapshot, manifest, and any publishing code changes in the product PR. Review the generated page diff when changing the public allowlist. Never export the whole vault. CI and the deployed site do not require vault access or a private-repository token.

Preview locally

From the repository root:

BUNDLE_GEMFILE=site/Gemfile bundle install
BUNDLE_GEMFILE=site/Gemfile bundle exec jekyll serve --source site --destination site/_site --host 127.0.0.1

Open http://127.0.0.1:4000/admin_suite/. Keep the /admin_suite/ prefix so local links behave as they will on GitHub Pages. The theme provides mobile navigation, heading anchors, code-copy buttons, and keyboard-accessible search.

Validate

bin/export-docs --verify
BUNDLE_GEMFILE=site/Gemfile bundle exec jekyll build --source site --destination site/_site --strict_front_matter
BUNDLE_GEMFILE=site/Gemfile bundle exec ruby bin/check-docs site/_site

The first command validates the checked-in snapshot against its manifest and the current exporter/allowlist. It detects missing, modified, or extra generated files. It cannot detect later vault edits without vault access; run the separate source --check command above whenever updating the documentation.

The rendered-site check validates public pages, local links and anchors, assets, search coverage, and exclusion of build inputs. The site configuration, generated snapshot, and Jekyll dependencies are excluded from the RubyGem.

GitHub Pages setup and deployment

In the repository’s Settings → Pages → Build and deployment, set Source to GitHub Actions. Use the github-pages environment and restrict deployments to main. The workflow needs no personal access token: only its deployment job receives pages: write and id-token: write.

Pull requests build and validate the site without deploying. Pushes to main and manual dispatches build it too; only the upstream repository’s main branch can deploy. Deployment waits for the documentation build and link checks. The deployment step records the public URL in the environment.

Documentation publication is independent of gem publishing. For the initial rollout, merge the 0.6.2 bump and verify its gem publication before merging the 0.7.0 documentation PR. The footer takes its version from the gem version constant at build time; there is no separate version to maintain.

To roll back the site, revert the publishing change on main or restore a known generated snapshot together with its matching exporter and allowlist. Re-run the Docs workflow and inspect the deployed installation guide, search, and mobile navigation. A source change requires a fresh export; do not edit generated pages to repair drift.