Skip to content
Documentation

ADR 0007: Decap CMS for Docs Editing

Status

Section titled “Status”

Accepted — 2026-01-28

Context

Section titled “Context”

The RCS internal documentation is maintained in Markdown/MDX files within a Git repository. While this approach provides excellent version control and developer workflow integration, it creates barriers for non-technical stakeholders who need to contribute to or review documentation.

Requirements

Section titled “Requirements”
  1. GUI editing for documentation without requiring Git knowledge
  2. Security through existing Cloudflare Access infrastructure
  3. No password management (magic-link authentication only)
  4. Git as source of truth (all changes version-controlled)
  5. Automatic deployment via existing Cloudflare Pages pipeline
  6. Minimal maintenance burden
  7. Monorepo-safe implementation (no impact on marketing site)

Constraints

Section titled “Constraints”
  • Must not introduce a separate user database
  • Must not require additional hosting infrastructure
  • Must integrate with existing GitHub repository
  • Must respect Cloudflare Access security boundaries
  • Must not add complexity to the build process

Decision

Section titled “Decision”

We will integrate Decap CMS (formerly Netlify CMS) into the Astro Starlight documentation site with the following architecture:

Implementation

Section titled “Implementation”

  1. Static CMS files in apps/docs/public/admin/

    • index.html: Minimal HTML shell loading Decap CMS from CDN
    • config.yml: CMS configuration with GitHub backend

  2. GitHub OAuth backend

    • Repository: adamsdsit/rcsweb_v2
    • Branch: main
    • Publish mode: Simple (direct commits, no editorial workflow)

  3. Two-layer authentication

    • Layer 1: Cloudflare Access (email magic-link)
    • Layer 2: GitHub OAuth (repository write access)

  4. Collections matching existing docs structure

    • Architecture, ADRs, Diagrams, Marketing, Platform, Security, Operations
    • All collections support MDX format with frontmatter

  5. No npm dependencies

    • CMS loaded from CDN (unpkg.com)
    • No build-time integration required
    • No Astro routes or components

Authentication Flow

Section titled “Authentication Flow”
Editor → Cloudflare Access (magic link) → CMS Interface → GitHub OAuth → Edit Content → Commit to GitHub → Cloudflare Pages Deploy

Alternatives Considered

Section titled “Alternatives Considered”

1. TinaCMS

Section titled “1. TinaCMS”

Pros:

  • Modern React-based UI
  • Real-time preview
  • Strong TypeScript support

Cons:

  • Requires npm dependencies and build integration
  • More complex setup and maintenance
  • Heavier bundle size
  • Overkill for our simple use case

Decision: Rejected due to complexity and maintenance burden.

2. Forestry.io / CloudCannon

Section titled “2. Forestry.io / CloudCannon”

Pros:

  • Hosted solution (no self-hosting)
  • Professional UI
  • Built-in media management

Cons:

  • Requires separate account/subscription
  • External dependency
  • Less control over authentication
  • Potential vendor lock-in

Decision: Rejected due to external dependency and cost.

3. Contentful / Sanity

Section titled “3. Contentful / Sanity”

Pros:

  • Powerful headless CMS
  • Rich content modeling
  • API-first approach

Cons:

  • Requires separate hosting
  • Git is no longer source of truth
  • Complex migration path
  • Overkill for markdown-based docs

Decision: Rejected because we want Git as the source of truth.

4. Custom Admin Interface

Section titled “4. Custom Admin Interface”

Pros:

  • Full control over features
  • Tailored to exact needs
  • No external dependencies

Cons:

  • Significant development time
  • Ongoing maintenance burden
  • Security responsibility
  • Reinventing the wheel

Decision: Rejected due to development and maintenance cost.

5. Direct GitHub Web Editor

Section titled “5. Direct GitHub Web Editor”

Pros:

  • No additional tools needed
  • Native Git integration
  • Zero setup

Cons:

  • Poor UX for non-technical users
  • No preview functionality
  • Requires GitHub account knowledge
  • No media upload workflow

Decision: Rejected due to poor UX for non-technical stakeholders.

Consequences

Section titled “Consequences”

Positive

Section titled “Positive”
  1. Low maintenance: CMS updates automatically from CDN
  2. No user database: Cloudflare Access handles authentication
  3. Full audit trail: All changes tracked in Git history
  4. Automatic deployment: Existing Cloudflare Pages pipeline
  5. Monorepo-safe: No impact on marketing site or other packages
  6. Security: Two-layer authentication (Cloudflare Access + GitHub OAuth)
  7. Rollback-friendly: Delete public/admin to disable CMS
  8. No build complexity: Static files only, no npm dependencies

Negative

Section titled “Negative”
  1. Manual setup required: GitHub OAuth and Cloudflare Access must be configured manually
  2. Limited preview: No real-time preview (must commit to see changes)
  3. GitHub dependency: Editors must have GitHub accounts with repo access
  4. Netlify OAuth dependency: Uses Netlify’s OAuth service even when not hosted on Netlify
  5. No editorial workflow: Direct commits to main (no draft/review states)

Neutral

Section titled “Neutral”
  1. CDN dependency: CMS loaded from unpkg.com (acceptable risk)
  2. Email-based access: Editors must use approved email addresses
  3. Session duration: 24-hour Cloudflare Access sessions (requires daily re-authentication)

Implementation Notes

Section titled “Implementation Notes”

File Structure

Section titled “File Structure”
apps/docs/
├── public/
│   └── admin/
│       ├── index.html          # CMS interface shell (13 lines)
│       └── config.yml          # CMS configuration (118 lines)
├── ADMIN_ACCESS.md             # Editor documentation (265 lines)
└── SETUP.md                    # Administrator guide (336 lines)

Security Boundaries

Section titled “Security Boundaries”

The CMS can ONLY edit:

  • Markdown/MDX files in src/content/docs
  • Upload images to public/images

The CMS CANNOT access:

  • Site configuration files
  • Build scripts or deployment settings
  • Marketing site (apps/site)
  • Repository settings or workflows
  • Other monorepo packages

Deployment

Section titled “Deployment”
  1. Commit CMS files to repository
  2. Cloudflare Pages automatically deploys
  3. Configure GitHub OAuth App
  4. Add environment variables to Cloudflare Pages
  5. Configure Cloudflare Access policy for /admin

Monitoring and Review

Section titled “Monitoring and Review”
  • Access audit: Review Cloudflare Access logs monthly
  • Commit audit: Review GitHub commit history for CMS commits
  • Editor list: Review approved editors quarterly
  • Security review: Annual review of OAuth tokens and access policies

References

Section titled “References”