Skip to content

Docs Deployment Verification

Use this page as the canonical operator checklist whenever the public Truthound docs portal is built, verified, or repaired.

Vercel automatic deployment

The truthound-docs project uses the Hobby plan and the GitHub repository seadonggyun4/Truthound. Pushes to main deploy the production documentation; other branches and pull requests produce authenticated Preview deployments. vercel.json owns the install command, build command, site output directory, and permanent /ko/ compatibility redirects. The install isolates its tools in a temporary virtual environment and uses Vercel's supplied Python interpreter with uv sync --frozen --extra docs. The Docs CI independently verifies the same lockfile with Python 3.11. Builds use the committed orchestration snapshot, not a moving upstream checkout. No API or serverless runtime is deployed.

The canonical address is https://truthound-docs.vercel.app/. Korean pages use /; English pages use /en/. Production is indexable; Vercel protects Preview URLs and applies its Preview indexing policy. Source-map protection stays enabled. The old hosting configuration is removed. Previously published package metadata cannot be rewritten; future packages and plugin updates carry the new links.

Vercel Configuration Checklist

  • [ ] Vercel source repository is seadonggyun4/Truthound
  • [ ] the production branch is main
  • [ ] the build command is sh docs/scripts/build_site.sh
  • [ ] the publish directory is site
  • [ ] the deployed site uses https://truthound-docs.vercel.app/ as the canonical docs URL
  • [ ] the docs operator runbook treats the public docs host as the only MkDocs deployment surface

Repo Configuration Checklist

  • [ ] mkdocs.yml sets site_url: https://truthound-docs.vercel.app/
  • [ ] mkdocs.yml builds from the staged full docs tree
  • [ ] mkdocs.public.yml builds from the staged public docs tree
  • [ ] vercel.json points at the repo-owned docs build script
  • [ ] docs/public_docs.yml defines the public docs manifest, including section prefixes and exclusions
  • [ ] docs/orchestration/ is a checked-in snapshot mirrored from truthound-orchestration
  • [ ] docs/ai/ is a locally maintained technical section describing the public truthound.ai contract
  • [ ] docs verification confirms dashboard and Workflow pages are not hosted inside the Vercel site
  • [ ] scripts/fetch-external-docs.sh orchestration is the canonical pre-release sync step for the orchestration snapshot
  • [ ] full and public docs staging run before the respective MkDocs builds
  • [ ] brand assets remain unchanged:
  • [ ] assets/truthound_banner.png
  • [ ] assets/truthound_icon.png remains a small static brand asset, not a MkDocs logo or favicon source
  • [ ] the existing palette configuration in both MkDocs configs
  • [ ] MkDocs configs do not set theme.logo or theme.favicon

Generated Site Checklist

After a local or Vercel build, confirm all of the following under site/:

  • [ ] site/index.html contains the 3.0 landing copy and expanded portal navigation
  • [ ] site/tutorials/index.html exists
  • [ ] site/cli/index.html exists
  • [ ] site/python-api/index.html exists
  • [ ] site/reference/index.html exists
  • [ ] site/ai/index.html exists and renders the AI overview
  • [ ] site/ai/system-boundary/index.html exists and renders the AI boundary document
  • [ ] site/orchestration/index.html exists and renders the Orchestration overview
  • [ ] site/orchestration/airflow/index.html exists and renders one platform page under the integrated section
  • [ ] site/orchestration/airflow/observability-alerting/index.html exists and renders an expanded platform subguide
  • [ ] site/orchestration/common/index.html exists and renders the shared runtime overview
  • [ ] site/orchestration/common/engine-resolution-selection/index.html exists and renders a shared runtime deep dive
  • [ ] site/orchestration/engines/index.html exists and renders the engine overview
  • [ ] site/orchestration/engines/capability-matrix/index.html exists and renders an advanced engine guide
  • [ ] site/orchestration/enterprise/index.html exists and renders the enterprise operations overview
  • [ ] site/orchestration/enterprise/rollout-topologies/index.html exists and renders an enterprise operations subguide
  • [ ] site/releases/latest-benchmark-summary/index.html exists and shows the verified benchmark numbers
  • [ ] site/releases/truthound-3.1/index.html exists and shows the AI surface and docs restructuring release note
  • [ ] site/sitemap.xml exists
  • [ ] site/search/search_index.json exists
  • [ ] the home page banner resolves from assets/truthound_banner.png
  • [ ] the benchmark summary icon banner resolves from assets/Truthound_icon_banner.png
  • [ ] the staged public docs tree reflects the public manifest expansion from docs/public_docs.yml
  • [ ] imported orchestration pages render the generated source banner and upstream edit link

Search and Sitemap Checklist

  • [ ] sitemap.xml contains exactly the number of pages declared by expected_page_count in docs/public_docs.yml
  • [ ] sitemap.xml includes:
  • [ ] home
  • [ ] tutorials
  • [ ] CLI reference
  • [ ] AI overview
  • [ ] AI system boundary
  • [ ] Python API reference
  • [ ] performance
  • [ ] benchmark methodology
  • [ ] Great Expectations comparison
  • [ ] latest verified benchmark summary
  • [ ] orchestration overview
  • [ ] orchestration airflow
  • [ ] orchestration shared runtime
  • [ ] orchestration shared runtime deep dive
  • [ ] orchestration engines
  • [ ] orchestration engines capability matrix
  • [ ] orchestration enterprise
  • [ ] orchestration enterprise rollout topologies
  • [ ] search_index.json contains exactly the number of pages declared by expected_page_count in docs/public_docs.yml
  • [ ] search_index.json contains:
  • [ ] TruthoundContext
  • [ ] ValidationRunResult
  • [ ] truthound.ai
  • [ ] Great Expectations
  • [ ] benchmark
  • [ ] release-grade
  • [ ] Truthound Orchestration
  • [ ] search_index.json contains imported orchestration families such as:
  • [ ] shared runtime
  • [ ] engine
  • [ ] enterprise
  • [ ] airflow
  • [ ] prefect
  • [ ] dbt
  • [ ] neither sitemap.xml nor search_index.json expose explicitly excluded duplicate legacy markdown files

Content Verification Checklist

  • [ ] the home page reads like a finished 3.0 release, not a transition snapshot
  • [ ] primary docs do not treat RC1 as the current release note
  • [ ] benchmark pages use release-grade, fixed-runner benchmark verification, or verified benchmark summary rather than repeated GA wording
  • [ ] README and the docs site agree on the current benchmark positioning against Great Expectations
  • [ ] Home, Core, AI, Orchestration, Release Notes, ADRs, and Legacy / Archive are all discoverable from the public nav
  • [ ] the Core nav exposes Getting Started, Tutorials, Guides, Reference, and Concepts & Architecture
  • [ ] dashboard and Workflow docs remain outside the public MkDocs surface
  • [ ] AI docs describe the additive truthound.ai namespace without implying core reverse-imports
  • [ ] imported orchestration pages identify truthound-orchestration as the upstream source repository
  • [ ] source-banner edit links target https://github.com/seadonggyun4/truthound-orchestration/edit/main/docs/...

Local Verification Commands

The full reference build retains optional Core UI documentation. Its Korean check uses --surface full, which permits only the three known Core UI link targets; it does not relax language thresholds or allow external UI links. The public build keeps the default strict route policy and public manifest exclusions. Validate each build before overwriting site/ with the next one.

sh scripts/fetch-external-docs.sh orchestration
python docs/scripts/prepare_public_docs.py --mode full
python docs/scripts/prepare_public_docs.py --mode public
python docs/scripts/check_links.py --mkdocs mkdocs.yml README.md CLAUDE.md build/full-docs
python docs/scripts/check_links.py --mkdocs mkdocs.public.yml build/public-docs
python -m mkdocs build --strict
python docs/scripts/verify_korean_docs.py --site-dir site --surface full
python -m mkdocs build --strict -f mkdocs.public.yml
python docs/scripts/verify_public_surface.py --manifest docs/public_docs.yml --site-dir site

Public deployment identity

After the public/Korean build gates, the build writes deployment-manifest.json containing only the source Git commit, package version and SHA-256 hashes of explicitly allowlisted public verification pages. The allowlist covers the MCP reference, focused MCP guide, reproducible example, established file/CLI entry pages, CI testing and deployment-verification pages in both languages. It does not collect environment variables, private records or arbitrary files. A deployment record is not evidence of Release CI success or PyPI publication.

Fetch https://truthound-docs.vercel.app/deployment-manifest.json, require source_commit to equal the intended final commit, then download each fixed public page and compare its exact response bytes with page_sha256. An old commit, missing page or hash mismatch remains a failed deployment check. The default Korean pages use /guides/.../; English uses /en/guides/.../. HTTP 200 and matching text alone do not prove the deployed commit.

Visitor and performance analytics

The production documentation uses Vercel Web Analytics and the free Speed Insights tier on Hobby. Preview and local builds do not send events. Query strings and fragments are removed before sending page URLs; custom events are not configured. Analytics measures documentation visits, not PyPI downloads. Speed Insights Plus is not enabled.