Skip to main content

Documentation Sharing Strategy for Small Teams

Private, AI-Accessible, MkDocs-Based Documentation with GitHub Access Control​

Combined Analysis | February 2026

Executive Summary

Chosen Solution: Markdown + MkDocs + GitHub​

For a small team (3-4 people) requiring private, AI-accessible documentation with GitHub-based access control, the recommended solution is:

Markdown files in a private GitHub organization repository, using MkDocs mkdocs.yml as the navigation manifest, with embedded AI metadata comments at the top of each document.

This architecture satisfies all stated requirements:

RequirementHow It's Satisfied
Private access via GitHubOrganization repo with granular roles (Read/Write/Maintain)
Online readingGitHub UI renders Markdown with auto-outline; optional MkDocs site
MCP access with securityGitHub MCP Server with fine-grained token scopes
Local AI accessgit clone provides full offline access
Separate AI commitsGitHub App or bot identity with distinct commit author
Manifest for quick scanningStandard mkdocs.yml nav section
Token-efficient AI scanningHTML comment metadata block at top of each doc

Why MkDocs over custom manifests:

  • Industry-standard YAML format already understood by documentation tooling
  • Human-readable navigation that doubles as machine-parseable index
  • Mature ecosystem with GitHub Pages integration
  • No custom tooling required for AI agents to parse

Key architectural decision: Use a dedicated documentation repository separate from code repos, allowing unified AI access across all projects while maintaining independent access control and commit history.

Part 1: Requirements Analysis

1.1 Core Constraints​

Your requirements define a "docs-as-code" baseline with specific security and AI-accessibility needs:

Access Control (GitHub-Derived)

  • If someone lacks GitHub repo access, they should also lack doc access
  • GitHub organization repositories offer granular roles (Read/Triage/Write/Maintain/Admin)
  • Personal-account private repos do NOT support read-only collaborators—avoid for this use case

Online + Local Parity

  • "Online" = GitHub web UI (always repo-gated) or private GitHub Pages (Enterprise Cloud only)
  • "Local" = git clone with full fidelity
  • Same content, same structure, same links work in both contexts

AI Token Efficiency

  • Agents should NOT ingest entire docs tree
  • A "thin index" (manifest + per-page metadata) enables targeted file fetching
  • MkDocs nav and embedded AI comments provide this capability

Controlled Writeback

  • AI writes via PRs with separate identity and separate commits
  • Branch protections, required reviews, and CODEOWNERS gate changes
  • Audit trail preserved in git history

1.2 Why Organization Repos Matter​

Account TypeRead-Only CollaboratorsGranular RolesBot-Friendly
Personal Private Repo❌ Not supported❌ No⚠️ Limited
Organization Private Repo✅ Yes✅ Read/Triage/Write/Maintain/Admin✅ Yes

Critical: GitHub explicitly states that "collaborators can't have read-only access" on private repos owned by a personal account. Use organization repos for proper access control.

Part 2: The MkDocs-Based Architecture

2.1 Repository Structure​

docs/                              # Dedicated documentation repo
├── mkdocs.yml                     # 📋 MANIFEST: Navigation + config
├── docs/                          # MkDocs content directory
│   ├── index.md                   # Landing page
│   ├── architecture/
│   │   ├── overview.md
│   │   ├── decisions/
│   │   │   ├── index.md
│   │   │   ├── adr-003-database.md
│   │   │   └── adr-002-api-design.md
│   │   └── diagrams/
│   │       └── system-context.md
│   ├── guides/
│   │   ├── getting-started.md
│   │   ├── deployment.md
│   │   └── troubleshooting.md
│   ├── api/
│   │   ├── overview.md
│   │   ├── authentication.md
│   │   └── endpoints.md
│   ├── projects/
│   │   ├── alpha/
│   │   │   ├── setup.md
│   │   │   └── api-reference.md
│   │   └── beta/
│   │       └── deployment.md
│   └── runbooks/
│       ├── incident-response.md
│       └── on-call-procedures.md
├── .github/
│   ├── CODEOWNERS                 # Path-based review requirements
│   └── workflows/
│       └── docs-ci.yml            # Validation + optional site build
└── .ai/
    └── instructions.md            # AI agent instructions

2.2 MkDocs Configuration as Manifest​

# mkdocs.yml - This IS your manifest for AI scanning
site_name: "Team Documentation"
site_description: "Private documentation for our organization"

# Theme configuration (optional - for rendered site)
theme:
  name: material
  features:
    - navigation.sections
    - navigation.expand
    - search.highlight

# ============================================
# NAVIGATION MANIFEST - AI agents read this
# ============================================
nav:
  - Home: index.md
  
  - Architecture:
    - Overview: architecture/overview.md
    - Decisions:
      - architecture/decisions/index.md
      - "ADR-001: Database Choice": architecture/decisions/adr-003-database.md
      - "ADR-002: API Design": architecture/decisions/adr-002-api-design.md
    - Diagrams: architecture/diagrams/system-context.md
  
  - Guides:
    - Getting Started: guides/getting-started.md
    - Deployment: guides/deployment.md
    - Troubleshooting: guides/troubleshooting.md
  
  - API Reference:
    - Overview: api/overview.md
    - Authentication: api/authentication.md
    - Endpoints: api/endpoints.md
  
  - Projects:
    - Project Alpha:
      - Setup: projects/alpha/setup.md
      - API Reference: projects/alpha/api-reference.md
    - Project Beta:
      - Deployment: projects/beta/deployment.md
  
  - Runbooks:
    - Incident Response: runbooks/incident-response.md
    - On-Call Procedures: runbooks/on-call-procedures.md

# Plugins (optional)
plugins:
  - search
  - git-revision-date-localized

# Extensions for better Markdown
markdown_extensions:
  - admonition
  - codehilite
  - toc:
      permalink: true

Why this works for AI:

  • Single YAML file contains complete navigation tree
  • Agent reads ~50 lines to understand entire doc structure
  • Human-readable titles map to file paths
  • Hierarchical structure shows relationships
  • Standard format—no custom parsing needed

2.3 AI Metadata Comments in Documents​

Each document includes an HTML comment block at the top for AI scanning. This is invisible in rendered output but parseable by agents.


# Architecture Overview

This document describes our system architecture...

Metadata Fields:

FieldPurposeAI Usage
titleDocument titleDisplay/reference
summary1-3 sentence descriptionDecide relevance without reading full doc
keywordsSearchable termsMatch to user queries
relatedCross-referencesNavigate related content
last-verifiedFreshness indicatorPrioritize current docs
priorityhigh/medium/lowFilter for importance

Example AI Workflow:

  1. Agent reads mkdocs.yml nav → understands structure (~50 tokens)
  2. Agent identifies candidate files from nav titles
  3. Agent reads only the @ai-metadata comment from each candidate (~30 tokens each)
  4. Agent fetches full content only for relevant files
  5. Result: 90%+ token savings vs scanning everything

2.4 Document Template​


# [Document Title]

## Overview

[Brief introduction - what this document covers and who it's for]

## [Main Sections]

[Content organized with clear headers]

## Related Documents

- [Link to related doc 1](../path/to/doc1.md)
- [Link to related doc 2](../path/to/doc2.md)

---
*Last updated: [Date] | Maintainer: [@username]*

Part 3: Access Control & Security

3.1 GitHub Permission Strategy​

┌─────────────────────────────────────────────────────────────┐
│                    Organization: your-org                    │
├─────────────────────────────────────────────────────────────┤
│  docs (private repo)                                        │
│  ├── Team: doc-readers     → Read access                   │
│  ├── Team: doc-writers     → Write access                  │
│  ├── Team: doc-maintainers → Maintain access               │
│  └── App: claude-docs-bot  → Write access (scoped)         │
└─────────────────────────────────────────────────────────────┘

CODEOWNERS File:

# .github/CODEOWNERS

# Default owners for everything
* @your-org/doc-maintainers

# Architecture docs require tech lead review
/docs/architecture/ @your-org/tech-leads

# Runbooks require ops team review  
/docs/runbooks/ @your-org/ops-team

# API docs require API team review
/docs/api/ @your-org/api-team

3.2 AI Agent Authentication Options​

Pros: Fine-grained permissions, short-lived tokens, better audit trail Setup: Create GitHub App → Install on org → Generate installation token

# AI agent configuration
github_app:
  app_id: 123456
  installation_id: 789012
  private_key_path: /secrets/github-app.pem
  permissions:
    contents: write      # Read/write repo contents
    pull_requests: write # Create PRs
    metadata: read       # Read repo metadata

Option B: Fine-Grained PAT​

Pros: Simpler setup for small teams Cons: Tied to user account, rotation overhead

# Create token with minimal scopes
gh auth token --scopes "repo:contents:write,repo:pull_requests:write"

Option C: GitHub Actions with GITHUB_TOKEN​

Pros: No secrets management, repo-scoped, auto-expires Use case: "Agent-in-CI" pattern where AI runs as workflow job

# .github/workflows/ai-docs-update.yml
name: AI Documentation Update
on:
  workflow_dispatch:
    inputs:
      task:
        description: 'Documentation task for AI'
        required: true

jobs:
  update-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: Run AI documentation update
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # AI agent uses GITHUB_TOKEN for commits/PRs
          ./scripts/ai-docs-update.sh "${{ inputs.task }}"

3.3 Branch Protection Rules​

# Branch protection for 'main'
protection_rules:
  main:
    required_reviews: 1
    require_codeowner_review: true
    require_status_checks:
      - "docs-validation"
      - "link-checker"
    restrict_pushes:
      - teams: [doc-maintainers]
      - apps: [claude-docs-bot]
    require_linear_history: true

3.4 MCP Server Security​

GitHub MCP Server Configuration:

{
  "mcpServers": {
    "github-docs": {
      "command": "npx",
      "args": ["-y", "@github/mcp-server"],
      "env": {
        "GITHUB_TOKEN": "${DOCS_GITHUB_TOKEN}",
        "GITHUB_TOOLSETS": "repos,pull_requests"
      }
    }
  }
}

Security Considerations:

  • Use scoped tokens (repo-specific, minimal permissions)
  • Enable Lockdown mode for public repos to filter untrusted content
  • Keep MCP servers updated (CVE-2025-68145 showed path validation issues)
  • Monitor MCP activity in audit logs (Enterprise feature)

Part 4: Alternative Systems Analysis

4.1 Notion​

Overview​

Notion provides excellent real-time collaboration with a rich block-based editor. It has an official MCP server for AI integration.

MCP Integration​

{
  "mcpServers": {
    "notion": {
      "command": "npx", 
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "${NOTION_TOKEN}"
      }
    }
  }
}

Available Tools:

  • notion-search - Search workspace content
  • notion-fetch - Retrieve page content (returns Markdown-ish format)
  • create-a-page - Create new pages
  • update-page-content - Modify existing pages

Assessment Against Requirements​

RequirementNotion SupportNotes
Private access via GitHub❌Separate Notion ACLs; broadest access applies
Online reading✅Excellent web UI
MCP access✅Official server, OAuth support
Local AI access❌Critical gap: No local clone capability
Separate AI commits❌No git history; API changes only
Manifest for scanning⚠️Database structure, but recursive API calls needed
Plain Markdown❌Proprietary format; exports are lossy

When Notion Makes Sense​

  • Real-time collaboration is the top priority
  • Team is non-technical and needs visual editing
  • Documentation is standalone (not tied to code workflows)
  • Willing to sacrifice local access and git history

Notion Limitations​

  • Lossy exports: Callouts become raw HTML, toggles lose interactivity
  • Rate limits: 3 requests/second; AI bulk operations hit limits quickly
  • No offline mode: Requires internet for full functionality
  • ACL model: "Broadest access applies"—harder to restrict than GitHub

4.2 Obsidian​

Overview​

Obsidian is a powerful local-first Markdown editor with a rich plugin ecosystem. It works well as an editing layer on top of a Git-backed documentation system.

MCP Integration​

Multiple MCP servers available:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/vault"],
      "env": {
        "OBSIDIAN_API_KEY": "${OBSIDIAN_API_KEY}"
      }
    }
  }
}

Requires: Obsidian Local REST API plugin running

Available Tools:

  • Read, write, search notes
  • Manage frontmatter/tags
  • Full-text search across vault
  • Patch notes for minimal updates

Assessment Against Requirements​

RequirementObsidian SupportNotes
Private access via GitHub⚠️Obsidian itself is not ACL layer; relies on Git repo
Online reading⚠️No native online—use GitHub UI or publish tools
MCP access✅Multiple servers; requires REST API plugin
Local AI access✅Vault is local Markdown files
Separate AI commits⚠️Requires Obsidian Git plugin or external sync
Manifest for scanning⚠️No native manifest; relies on folder structure
Plain Markdown✅Native format with YAML frontmatter

Use Obsidian as editing UI, Git as truth:

┌─────────────────────────────────────────────────────────────┐
│  Local Machine                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │  Obsidian   │───▶│  Local Git  │───▶│   GitHub    │    │
│  │   (edit)    │    │   (sync)    │    │  (truth)    │    │
│  └─────────────┘    └─────────────┘    └─────────────┘    │
└─────────────────────────────────────────────────────────────┘
  1. Clone docs repo locally
  2. Open repo folder as Obsidian vault
  3. Use Obsidian Git plugin for commit/push
  4. GitHub remains source of truth and access control

When Obsidian Makes Sense​

  • Team members want rich local editing experience
  • Graph visualization helps understand doc relationships
  • Already comfortable with Git workflows
  • Willing to maintain sync tooling

Obsidian Limitations​

  • Requires app installation on each machine
  • Git sync is plugin-based (not native)
  • No built-in manifest—must adopt MkDocs or similar externally
  • MCP requires REST API plugin running

4.3 Comparison Matrix​

CriteriaGitHub + MkDocsObsidian + GitNotion
Meets all requirements✅ Yes⚠️ Partial❌ No
GitHub auth = doc auth✅ Native⚠️ Via repo❌ Separate
Local AI access✅ Git clone✅ Vault files❌ API only
Standard manifest✅ mkdocs.yml❌ Custom needed❌ Database
Plain Markdown✅ Native✅ Native❌ Proprietary
Real-time collab❌ Git-based❌ Git-based✅ Excellent
Setup complexityLowMediumLow
Team learning curveMedium (Git)High (Git + Obsidian)Low

Part 5: Implementation Guide

5.1 Phase 1: Repository Setup (Week 1)​

Create Organization and Repo​

# Create new docs repo in organization
gh repo create your-org/docs --private --description "Team documentation"

# Clone locally
git clone git@github.com:your-org/docs.git
cd docs

Initialize MkDocs Structure​

# Create directory structure
mkdir -p docs/{architecture/decisions,guides,api,projects,runbooks}
mkdir -p .github/workflows
mkdir -p .ai

# Create initial mkdocs.yml
cat > mkdocs.yml << 'EOF'
site_name: "Team Documentation"
docs_dir: docs

nav:
  - Home: index.md
  - Architecture:
    - Overview: architecture/overview.md
  - Guides:
    - Getting Started: guides/getting-started.md
EOF

# Create landing page with AI metadata
cat > docs/index.md << 'EOF'

# Team Documentation

Welcome to our documentation. Use the navigation to find what you need.

## Quick Links

- [Architecture Overview](architecture/overview.md)
- [Getting Started Guide](guides/getting-started.md)
EOF

Configure Branch Protection​

# Via GitHub CLI
gh api repos/your-org/docs/branches/main/protection -X PUT \
  -F required_status_checks='{"strict":true,"contexts":["docs-validation"]}' \
  -F enforce_admins=false \
  -F required_pull_request_reviews='{"required_approving_review_count":1}'

Add CODEOWNERS​

cat > .github/CODEOWNERS << 'EOF'
* @your-org/doc-maintainers
/docs/architecture/ @your-org/tech-leads
/docs/runbooks/ @your-org/ops-team
EOF

5.2 Phase 2: AI Integration (Week 2)​

Create AI Instructions File​

cat > .ai/instructions.md << 'EOF'
# AI Agent Instructions for Documentation

## Reading Documentation

1. **Start with mkdocs.yml** - Read the `nav` section to understand structure
2. **Check @ai-metadata comments** - Each doc has a metadata block at the top
3. **Priority levels:**
   - high: Core architecture, getting started
   - medium: API reference, project-specific docs
   - low: Runbooks, historical decisions

## Writing Documentation

1. **Always include @ai-metadata block** at the top of new documents
2. **Update mkdocs.yml nav** when adding new files
3. **Use relative links** between documents
4. **Follow existing structure** - check similar docs for format

## Commit Guidelines

- Commit as: `Claude <claude@your-org.com>`
- Message format: `docs: <description>`
- Always create PR, never push directly to main
- Reference related issues/discussions in PR description

## Token Optimization

- Read mkdocs.yml nav first (~50 tokens)
- Read only @ai-metadata blocks to assess relevance (~30 tokens each)
- Fetch full content only for confirmed-relevant files
EOF

Configure GitHub MCP Server​

For Claude Desktop / Claude Code:

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@github/mcp-server"],
      "env": {
        "GITHUB_TOKEN": "${DOCS_GITHUB_TOKEN}"
      }
    }
  }
}

For Cursor / Windsurf:

{
  "mcpServers": {
    "github-docs": {
      "command": "npx",
      "args": ["-y", "@github/mcp-server"],
      "env": {
        "GITHUB_TOKEN": "${DOCS_GITHUB_TOKEN}",
        "GITHUB_TOOLSETS": "repos,pull_requests"
      }
    }
  }
}
  1. Go to GitHub → Settings → Developer Settings → GitHub Apps
  2. Create new app with permissions:
    • Contents: Read & Write
    • Pull requests: Read & Write
    • Metadata: Read
  3. Install on your organization
  4. Generate private key for authentication

5.3 Phase 3: CI/CD Setup (Week 2-3)​

Documentation Validation Workflow​

# .github/workflows/docs-ci.yml
name: Documentation CI

on:
  pull_request:
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install MkDocs
        run: pip install mkdocs mkdocs-material
      
      - name: Validate MkDocs config
        run: mkdocs build --strict
      
      - name: Check for broken links
        uses: lycheeverse/lychee-action@v1
        with:
          args: --verbose --no-progress 'docs/**/*.md'
          fail: true

  ai-metadata-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check AI metadata presence
        run: |
          for file in $(find docs -name "*.md"); do
            if ! grep -q "@ai-metadata" "$file"; then
              echo "WARNING: $file missing @ai-metadata block"
            fi
          done

5.4 Phase 4: Team Onboarding (Week 3-4)​

Contribution Workflow​

┌─────────────────────────────────────────────────────────────────┐
│                     Documentation Workflow                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Human Author              │        AI Author                   │
│  ─────────────             │        ─────────                   │
│  1. Create branch          │        1. Receive task             │
│  2. Edit in editor/        │        2. Read mkdocs.yml          │
│     Obsidian               │        3. Read @ai-metadata        │
│  3. Add @ai-metadata       │        4. Create branch            │
│  4. Update mkdocs.yml      │        5. Write/edit docs          │
│  5. Open PR                │        6. Update mkdocs.yml        │
│  6. Request review         │        7. Open PR                  │
│                            │        8. Human reviews            │
│  ◄─────────────────────────┼────────────────────────────────►  │
│                            │                                     │
│                    Both: PR merged to main                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Quick Reference Card for Team​

## Documentation Quick Reference

### Adding a New Document
1. Create file in appropriate `docs/` subdirectory
2. Add @ai-metadata block at top (copy from template)
3. Add entry to `mkdocs.yml` nav section
4. Create PR with title: `docs: Add <document name>`

### AI Metadata Template

### File Naming
- Use lowercase with hyphens: `api-authentication.md`
- ADRs: `adr-NNN-short-title.md`
- Keep names descriptive but concise

Part 6: Monorepo vs Polyrepo for Documentation

6.1 Recommendation: Dedicated Docs Monorepo​

For a 3-4 person team, a separate documentation repository provides the best balance:

your-org/
├── project-alpha/          # Code repo
├── project-beta/           # Code repo  
├── project-gamma/          # Code repo
└── docs/                   # ← Dedicated docs monorepo
    ├── mkdocs.yml
    ├── docs/
    │   ├── shared/         # Cross-project docs
    │   ├── architecture/   # Overall system docs
    │   ├── projects/
    │   │   ├── alpha/      # Project-specific docs
    │   │   ├── beta/
    │   │   └── gamma/
    │   └── runbooks/
    └── .github/

6.2 Why This Structure Works​

BenefitExplanation
Single MCP connectionAI reads all docs from one repo
Unified searchCross-project discovery is easy
Separate access controlDoc readers ≠ code contributors
Independent historyDoc commits don't pollute code history
Centralized standardsOne mkdocs.yml, one template, one workflow
Cross-project linkingSimple relative paths between project docs

6.3 When to Embed Docs in Code Repos​

Consider docs-alongside-code if:

  • Documentation is tightly coupled to code (API docs from code comments)
  • Single project only, no cross-project docs
  • Want docs versioned exactly with code releases
  • Using tools like Rust's cargo doc or Python's Sphinx autodoc

6.4 Reference: Alternative Structures​

Option A: Docs in Each Code Repo​

project-alpha/
├── src/
├── docs/           # Project-specific docs only
│   └── README.md
└── mkdocs.yml

project-beta/
├── src/
├── docs/
└── mkdocs.yml

Pros: Docs versioned with code Cons: AI needs multiple repo access, no unified search, duplication of shared content

Option B: Full Monorepo (Code + Docs)​

monorepo/
├── apps/
│   ├── alpha/
│   └── beta/
├── libs/
├── docs/           # All docs here
│   └── mkdocs.yml
└── nx.json         # or turborepo.json

Pros: Everything in one place, atomic changes across code+docs Cons: Requires monorepo tooling (Nx, Turborepo), complex CI, all-or-nothing access

Part 7: Conclusion

The Chosen Solution​

Markdown files + MkDocs manifest + GitHub organization repository is the optimal documentation strategy for your small team because:

  1. GitHub IS the access control layer - No separate auth system, no sync issues, permission model maps directly to docs access

  2. MkDocs provides a standard manifest - The nav section in mkdocs.yml is human-readable AND machine-parseable, eliminating need for custom tooling

  3. AI metadata comments enable token efficiency - The @ai-metadata pattern lets agents assess document relevance in ~30 tokens instead of reading entire files

  4. Local access is a git clone away - Full offline capability for humans and AI agents alike

  5. Git history = audit trail - Every change tracked, attributed, reversible; AI commits are clearly identifiable

  6. Dedicated docs repo balances concerns - Unified AI access across projects, separate from code churn, independent access control

Implementation Checklist​

Must Have (Week 1-2)​

  • Create organization-owned private docs repository
  • Configure mkdocs.yml with nav structure
  • Add @ai-metadata template to all documents
  • Configure branch protection rules
  • Test GitHub MCP Server connection

Should Have (Week 2-3)​

  • Create GitHub App for AI authentication
  • Set up CI workflow for doc validation
  • Create .ai/instructions.md for agents
  • Document contribution workflow for team
  • Migrate existing documentation with metadata

Nice to Have (Week 4+)​

  • Configure MkDocs Material theme for web viewing
  • Deploy to Cloudflare Pages with Access for private hosting (see below)
  • Create Obsidian vault overlay for rich editing
  • Build custom AI workflows via GitHub Actions
  • Add search indexing for larger doc sets
  • Add CODEOWNERS for path-based review requirements (e.g., architecture docs require tech lead review)

Private Hosting: Cloudflare Pages + Access​

GitHub Pages on free plans are always public. For private hosted docs without Enterprise pricing:

Cloudflare Pages + Cloudflare Access (Zero Trust)

  • Cloudflare Pages hosts the MkDocs static site (free tier)
  • Cloudflare Access gates the site behind authentication (free for up to 50 users)
  • Auth options: email OTP, GitHub OAuth, or Google Workspace
  • Site served on *.pages.dev subdomain (custom domain optional)

GitHub Actions deployment: Fully supported. Cloudflare provides an official cloudflare/wrangler-action for deploying from GitHub Actions. The workflow would:

  1. Build MkDocs on push to main
  2. Deploy the site/ output to Cloudflare Pages via Wrangler
  3. Cloudflare Access enforces auth — no public exposure

Secrets required: CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in GitHub repo secrets.

Why not other options:

  • GitHub Pages (free) — always public, not acceptable for private docs
  • Azure Static Web Apps — viable (we use Azure), but Cloudflare Access auth is simpler to configure
  • Self-hosted — unnecessary infrastructure overhead for static docs

Final Architecture Diagram​

┌─────────────────────────────────────────────────────────────────────┐
│                        Documentation System                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────────────┐   │
│  │   GitHub    │     │  MkDocs     │     │    AI Agents        │   │
│  │Organization │────▶│  mkdocs.yml │────▶│    (via MCP)        │   │
│  │Private Repo │     │  (manifest) │     │                     │   │
│  └─────────────┘     └─────────────┘     │  1. Read nav        │   │
│         │                   │            │  2. Read @ai-meta   │   │
│         │                   │            │  3. Fetch relevant  │   │
│         ▼                   ▼            │  4. Create PR       │   │
│  ┌─────────────┐     ┌─────────────┐     └─────────────────────┘   │
│  │ Access via: │     │ docs/*.md   │              │                 │
│  │ • GitHub UI │     │ with        │              │                 │
│  │ • git clone │     │ @ai-metadata│◀─────────────┘                 │
│  │ • MCP Server│     │ comments    │                                │
│  └─────────────┘     └─────────────┘                                │
│                                                                      │
│  Access Control: Organization roles (Read/Write/Maintain)           │
│  Review: CODEOWNERS + branch protection + required reviews          │
│  History: Git commits with clear attribution (human vs AI)          │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

This analysis combines research from multiple sources to provide a comprehensive documentation strategy tailored for small teams with specific privacy, AI-accessibility, and workflow requirements.

Last updated: February 2026