Skip to content

fix(docs): add mkdocs.yml at repo root and minimal page stubs - #6

Merged
adris-misra merged 1 commit into
mainfrom
phase-9/mkdocs-config
Jun 2, 2026
Merged

adris-misra merged 1 commit into
mainfrom
phase-9/mkdocs-config

Conversation

@adris-misra

Copy link
Copy Markdown
Owner

Phase

Phase 9 follow-up: MkDocs site config

Summary

Resolves the post-merge Build MkDocs Site failure on main (commit
9a740da). The docs-publish workflow was added in Phase 1 but the
mkdocs.yml config it depends on was never created — Phase 1 spec §3.2
listed it under docs/, but the standard MkDocs convention (and what the
workflow expects) is at the repo root.

What changed

  • mkdocs.yml at repo root — Material theme, full nav, pymdownx extensions
  • docs/architecture/overview.md — 10-agent pipeline diagram, design
    principles, agent roles table
  • docs/architecture/uns_context_broker.md — zone enforcement, topic
    format reference, API example
  • docs/standards/standards_alignment.md — full standards matrix
    (ISA-95, MQTT Sparkplug B, OPC UA, NIST SP 800-82, CMMC L2, NIST AI RMF,
    ISO 42001, ISO 14224)
  • docs/governance/ai_rmf_profile.md — GOVERN/MAP/MEASURE/MANAGE
    function mapping with code examples
  • docs/case_studies/smm_starter.md — 5-minute local Ollama quickstart
    for SMMs (NIST MEP-audience targeted)
  • docs/case_studies/chips_supplier.md — Bedrock/GovCloud deployment
    for CHIPS Act Tier-2/Tier-3 suppliers
  • pyproject.toml — added [docs] extras group with mkdocs-material>=9.5
    and pymdown-extensions>=10.0
  • docs/index.md and docs/governance/cmmc_l2_mapping.md left untouched
    (already existed with substantive content)

Acceptance criteria covered

  • mkdocs build --strict passes with zero warnings
  • All nav entries reference existing files
  • Standard MkDocs convention (config at repo root, docs_dir: docs)
  • No changes to existing docs with substantive content
  • No changes to the docs-publish workflow itself

How to verify

pip install -e ".[docs]"
mkdocs build --strict
mkdocs serve  # optional, opens local preview at :8000

Why this matters for the project

GitHub Pages will auto-deploy on merge, producing a citable docs URL at
https://adris-misra.github.io/multi-agentic-framework/ — the docs site
itself becomes a public, dated, citable artifact.

Out of scope

  • Substantive content authoring for docs/index.md and cmmc_l2_mapping.md
    beyond what's already there
  • Whitepaper polish (separate follow-up)

The docs-publish workflow expected mkdocs.yml at the repo root; the file
was previously absent (Phase 1 spec placed it at docs/mkdocs.yml which
is non-standard). This commit:

- Adds mkdocs.yml at the repo root with mkdocs-material theme, full nav,
  and all required markdown extensions
- Creates stub pages for the 6 nav entries that had no content file:
  docs/architecture/overview.md
  docs/architecture/uns_context_broker.md
  docs/standards/standards_alignment.md
  docs/governance/ai_rmf_profile.md
  docs/case_studies/smm_starter.md
  docs/case_studies/chips_supplier.md
- Leaves docs/index.md and docs/governance/cmmc_l2_mapping.md untouched
  (they already have substantive content)
- Adds [project.optional-dependencies] docs = [mkdocs-material, pymdown-extensions]
  to pyproject.toml

Verified: mkdocs build --strict completes with 0 warnings.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@adris-misra
adris-misra merged commit 875befa into main Jun 2, 2026
8 checks passed
@adris-misra
adris-misra deleted the phase-9/mkdocs-config branch June 2, 2026 15:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant