Skip to content

How This Site Works

This site is intentionally simple.

On the surface, you can see there is:

  • No CMS
  • No database
  • No runtime dependencies

It is Markdown in Git, built into static HTML.

But under the hood, there is deliberate structure.

The site leverages GitHub Actions and constrained Copilot agents to:

  • Process new content through structured intake workflows
  • Enforce validation and coherence rules before publication
  • Propagate canonical architecture changes
  • Periodically audit the documentation graph for drift

What appears minimal is backed by automation.

The simplicity is architectural, not accidental.

High Level Architecture

Stack:

  • MkDocs
  • Material for MkDocs
  • Private GitHub repository
  • GitHub Actions
  • GitHub Pages
  • Custom domain (halite.systems)

Everything is version controlled.

Every change is a commit.

Deployment is automatic.

Repository Structure

The layout is predictable and flat:

docs/
  blog/
    posts/
      YYYY-MM-DD-title.md
  guides/
  architecture/
  kb/
  snippets/
  about/
  _backlog/
mkdocs.yml

Key decisions:

  • Blog posts are date-prefixed.
  • Guides and architecture documents are manually indexed in navigation.
  • Backlog items live in docs/_backlog/.
  • No dynamic rendering.
  • No server-side components.

The site root resolves directly to the blog.

Automation Model

The documentation system is structured as a controlled pipeline.

All content — human or agent-produced — flows through the same validation boundary.

The diagram below shows the full control loop.

End-to-End Control Flow Diagram

flowchart TD
    A[Customer Guide] --> B[docs/_backlog/]
    B --> C[backlog-intake.yml]
    C --> D[Issue agent:kb]
    D --> E[@copilot dispatch]

    E --> F[Branch + PR]
    F --> G[Validation Harness]

    G -->|Fail| E
    G -->|Pass| H[Merge]

    H --> I[MkDocs Build]
    I --> J[Deploy]

    H --> K[Architecture Change?]
    K -->|Yes| L[Propagation Issue]
    L --> E

    H --> M[Weekly Sweep]
    M --> N[Sweep Issue]
    N --> E

The validation harness is the choke point.

All paths converge there.

Validation Harness (harness.yml)

Every Pull Request triggers the validation workflow.

This is the single enforcement boundary.

The harness performs:

  • Frontmatter validation (validate_content.py)
  • Heading structure checks
  • Internal link validation (check_internal_links.py)
  • Site index generation (build_site_index.py)
  • Coherence enforcement (enforce_coherence.py)
  • Markdown linting
  • Strict MkDocs build (mkdocs build --strict)

If any step fails:

  • The PR does not merge.
  • No deployment occurs.

Validation enforces more than formatting. It enforces structural rules:

  • Required See also sections
  • Canonical architecture references
  • Tag consistency
  • Navigation coherence
  • Internal link integrity

No gate pass, no merge.

Backlog Intake (backlog-intake.yml)

New content begins in:

docs/_backlog/

Each file is a sanitised, customer-derived implementation guide.

When a file is pushed into _backlog/, the backlog-intake workflow:

  1. Detects new or modified backlog files.
  2. Ensures the agent:kb label exists.
  3. Creates a GitHub Issue per backlog file.
  4. Embeds structured processing instructions.
  5. Applies the agent:kb label.

The Issue becomes the execution context.

Nothing is processed directly from the file system.

Auto Dispatch (auto-dispatch-kb.yml)

When an Issue is opened or labeled agent:kb:

  • The workflow posts an @copilot comment.
  • Structured instructions are re-injected.
  • AGENTS.md is referenced.

Copilot is not autonomous. It is explicitly dispatched through issue labeling.

The agent operates inside the issue boundary.

PR-Based Publication Model

Once dispatched, the agent:

  1. Creates a new branch.
  2. Processes the referenced _backlog file only.
  3. Routes it to one of three locations:
    • docs/guides/...
    • docs/architecture/...
    • docs/snippets/...
  4. Optionally drafts a blog announcement (based on rules).
  5. Opens a Pull Request referencing the intake issue.

Nothing commits to the default branch.

The PR is the review boundary.

Then the harness runs.

Canonical Architecture Propagation (canonical-propagation-intake.yml)

Architecture pages are treated as canonical.

When any file under:

docs/architecture/

changes, a propagation workflow runs.

It:

  • Detects modified canonical files.
  • Creates an agent:kb-propagate issue.
  • Lists changed architecture documents.
  • Instructs the agent to:
  • Identify related pages via tags and link graph.
  • Update missing See also references.
  • Align example code with current canonical guidance.
  • Keep diffs minimal.
  • Open a PR.

Architecture changes cannot drift silently.

Downstream documentation is automatically reviewed.

Weekly Structural Sweep (kb-sweep.yml)

Once per week, a scheduled workflow audits the documentation graph.

It detects:

  • Isolated pages (no inbound links)
  • Missing tags
  • Missing See also sections
  • Missing canonical architecture references
  • Structural inconsistencies

If findings exist:

  • A agent:kb-sweep issue is opened.
  • The agent produces a minimal corrective PR.
  • The harness validates it.

Documentation is periodically audited, not just validated at change time.

Agent Constraints

The agent operates under strict rules:

  • Only process the referenced file.
  • Follow routing rules exactly.
  • Add correct YAML frontmatter.
  • Normalize headings (body starts at ##).
  • Apply appropriate tags.
  • Add required internal cross-links.
  • Remove customer-identifying information.
  • Keep diffs minimal.
  • Never commit directly to default branch.

The agent refactors. It does not author.

All technical substance originates from real implementation work.

Design Principles

  • Deterministic builds
  • Issue-driven intake
  • PR-gated publication
  • Canonical enforcement
  • Scheduled drift detection
  • No hidden state
  • Static output

Everything visible is generated from versioned source.

Summary

This site is:

  • Markdown
  • Git
  • Issue-driven automation
  • Instruction-constrained agent processing
  • Validation harness enforcement
  • Canonical propagation control
  • Scheduled structural auditing
  • Deterministic static deployment

It is documentation-as-code with an automated editorial control layer.

Nothing more.

And that is intentional.