Skip to content

HOWTO – Build and Preview Public and Academy Docs

Purpose: Show how to generate the audience-specific doc trees and static sites, and preview them locally.
Difficulty: Intermediate
Prerequisites:
- HybridOps repo cloned. - Python and virtualenv (or equivalent) available. - Able to run make from the repo root.

Demo (optional)

If you record a short walkthrough later, link it here.

Context

The documentation system produces two audience-specific sites from a single docs/ tree:

  • Public docs – for GitHub visitors, assessors, and hiring managers.
  • Academy docs – for HybridOps Academy learners.

The build pipeline:

  1. Scans docs/ and generates ADR, HOWTO, runbook, CI and showcase indexes.

  2. Applies the access/stub model to build:

  3. deployment/build/docs/public

  4. deployment/build/docs/academy

  5. Generates MkDocs configs and builds static sites:

  6. deployment/build/site/docs-public

  7. deployment/build/site/docs-academy

This HOWTO walks through those steps, how to preview the result, and how to build the academy variant for a separate paid-docs host.

Steps

1. Prepare the environment

From the repo root:

cd <your workspace root>  # the directory that contains hybridops-docs/
cd hybridops-docs
make docs.venv.refresh

Confirm mkdocs is available:

.local/venv/bin/mkdocs --version

Expected: mkdocs reports a version and exits with status 0 from .local/venv/bin/mkdocs. This repo intentionally builds with a frozen MkDocs 1.x / Material 9.x toolchain from control/requirements.lock.txt.

2. Generate indexes and audience-specific doc trees

Run the docs preparation target:

make docs.prepare

What this does:

  • Runs index generators under control/tools/indexing/.

  • Applies the access/stub model with:

  • control/tools/mkdoc/build_generator/build_mkdocs_trees.py

  • Produces the audience-specific trees:

  • deployment/build/docs/public

  • deployment/build/docs/academy

  • Generates MkDocs configs via:

  • control/tools/mkdoc/build_generator/build_mkdocs_configs.py

Expected results:

  • No errors in the terminal.
  • The paths above exist and contain Markdown trees filtered by audience.

  • New configs appear under control/tools/mkdoc/ and use repo-relative paths:

  • mkdocs.public.yml

  • mkdocs.academy.yml

3. Build the public and academy sites

From the repo root:

make docs.build

This runs:

  • .local/venv/bin/mkdocs build -f control/tools/mkdoc/mkdocs.public.yml
  • .local/venv/bin/mkdocs build -f control/tools/mkdoc/mkdocs.academy.yml

Expected results:

  • deployment/build/site/docs-public contains index.html and the docs structure.
  • deployment/build/site/docs-academy contains index.html and the docs structure.
  • Both site directories contain _worker.js, so the Pages Function proxy is available on public and academy hosts.
  • MkDocs reports “Documentation built” for both configs.

If the academy build is being published to a separate host, set the academy canonical URL before the build:

HYBRIDOPS_DOCS_ACADEMY_SITE_URL='https://learn-docs.hybridops.tech' make docs.build

That keeps the academy sitemap and canonical URLs aligned to the paid-docs host instead of the legacy /academy path on the public site.

4. Serve the built sites locally

For a simple static preview, use Python’s HTTP server.

Public docs:

python -m http.server --directory deployment/build/site/docs-public 8000
# Browse to http://127.0.0.1:8000

Academy docs (second terminal):

python -m http.server --directory deployment/build/site/docs-academy 8001
# Browse to http://127.0.0.1:8001

Expected results:

  • Public site at http://127.0.0.1:8000 shows public docs with stubs where appropriate.
  • Academy site at http://127.0.0.1:8001 shows full academy content.

5. Live reload with MkDocs (optional)

For development, use mkdocs serve with the generated configs:

.local/venv/bin/mkdocs serve -f control/tools/mkdoc/mkdocs.public.yml -a 127.0.0.1:8000
.local/venv/bin/mkdocs serve -f control/tools/mkdoc/mkdocs.academy.yml -a 127.0.0.1:8001

Expected results:

  • Local servers with automatic rebuild when you edit docs/.
  • Navigation and audience behaviour matching the static builds.

Validation

  • make docs.prepare and make docs.build complete without errors.
  • deployment/build/docs/public and deployment/build/docs/academy exist and contain filtered trees.
  • deployment/build/site/docs-public/index.html and deployment/build/site/docs-academy/index.html exist.
  • Public site:
  • Shows full content for access: public.
  • Shows stubs for access: academy where configured.
  • Academy site:
  • Shows full content for both public and academy documents.
  • If HYBRIDOPS_DOCS_ACADEMY_SITE_URL is set:
  • control/tools/mkdoc/mkdocs.academy.yml uses the paid-docs host as site_url.
  • deployment/build/site/docs-academy/sitemap.xml points at the paid-docs host.

For formal evidence, capture:

  • A short screen recording of building and browsing both sites.
  • Screenshots of ADR/runbook/HOWTO indices and at least one stubbed academy page.

Troubleshooting

  • Issue: mkdocs not found.
    Cause: The repo-local docs virtualenv has not been prepared.
    Fix: Refresh the docs virtualenv:
make docs.venv.refresh

  • Issue: Build fails with link warnings only.
    Cause: Missing HOWTO/runbook/diagram referenced by existing docs.
    Fix: Create the referenced file or update/remove the link. Warnings do not block the build unless strict: true is set.

  • Issue: 'bool' object has no attribute 'split' during MkDocs build.
    Cause: template: front-matter field set to true/false instead of a template name.
    Fix: Remove template: or rename it to is_template_doc: and set true/false.

  • Issue: Public and academy sites look identical.
    Cause: No documents marked with access: academy or stubs not enabled.
    Fix: Review ADR-0021/ADR-0022 and front matter of selected documents.

References

Maintainer: HybridOps License: MIT-0 for code, CC-BY-4.0 for documentation unless otherwise stated.