Building the Arbiter-Bot Documentation Site

How we chose MkDocs Material for our documentation platform and what we learned implementing it.

Context

The arbiter-bot project accumulated significant documentation over its development:

• Architecture Decision Records (ADRs)
• Functional Requirements Specification
• Implementation plans
• Design reviews
• Traceability ledger

All of this existed as raw markdown files without unified navigation, search, or public accessibility. More critically, our CLAUDE.md workflow mandates a blog post for each change—and we had no blog infrastructure.

Decision

We evaluated four alternatives:

Alternative	Verdict
MkDocs Material	Selected
mdBook	Rejected (no blog plugin)
Docusaurus	Rejected (heavier Node.js dependency)
GitHub Wiki	Rejected (limited navigation)

Primary driver: Organization alignment with amiable-templates.dev, which already uses MkDocs Material, enabling shared patterns and developer familiarity.

Implementation

Site Structure

We organized content into logical sections:

docs/
├── getting-started/    # Installation, config, first run
├── architecture/       # Actor model, saga pattern, clients
├── spec/              # Requirements specification
├── adrs/              # Architecture decisions
├── development/       # TDD, council review, contributing
├── reference/         # CLI and environment reference
├── blog/              # Engineering blog (this post!)
└── reviews/           # Council review documents

Content Migration

Existing documentation was reorganized:

• implementation.md → architecture/index.md
• ledger.md → development/ledger.md
• *_plan.md → development/plans/

Key Configuration

The mkdocs.yml enables Material theme features matching our reference site:

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.instant
    - search.suggest
    - content.code.copy

plugins:
  - blog
  - git-revision-date-localized

Security Considerations

Before publishing, we implemented a content review checklist:

• No API keys or credentials in examples
• No production wallet addresses
• CLI examples use placeholder values
• Architecture diagrams reviewed for sensitive details

Verification

1. Local build: mkdocs build --strict passes
2. Local preview: mkdocs serve renders correctly
3. Deployment: GitHub Actions workflow deploys to Pages
4. Council review: ADR-003 reviewed with reasoning tier (85% confidence)

Lessons Learned

1. Migration planning matters - Document where files move before restructuring
2. Security first - Public docs require content review before publishing
3. Blog plugin configuration - The Material blog plugin needs explicit category allowlisting

The site is now live at amiable-dev.github.io/arbiter-bot.