Skip to content

Docs Site (MkDocs + Cloudflare Pages) — Plan

Motivation

The docs/ folder has grown into a full reference — spec, implementation notes, and plans — but it's only readable by cloning the repo. A hosted site makes it browsable from anywhere with search, navigation, and rendered markdown without needing a GitHub account or a local clone.

Scope

In scope: - MkDocs + Material theme as the static site generator - Cloudflare Pages as the host (free tier, works with private repos) - Auto-deploy on every push to main that touches docs/ or mkdocs.yml

Out of scope: - Custom domain (nice-to-have later) - Obsidian local vault setup (separate, zero-code task — just open docs/ as a vault) - Any changes to the docs content itself

Approach

Files already created

  1. mkdocs.yml — site config, nav, Material theme (light/dark toggle, search, copy-code)
  2. docs/index.md — home page with stack table and doc layout overview
  3. .github/workflows/docs.yml — GitHub Actions workflow (kept for reference; Cloudflare Pages replaces the deploy step)

Remaining steps

  1. Push to main — commit the three files above
  2. Connect Cloudflare Pages to the repo
  3. Cloudflare Dashboard → Pages → Create a project → Connect to Git
  4. Select the kosungjunmichael/FinTrack repo
  5. Build settings:
    • Framework preset: None
    • Build command: pip install mkdocs-material && mkdocs build
    • Output directory: site
  6. Save and deploy
  7. Verify — Cloudflare provides a *.pages.dev URL; confirm the nav and search work
  8. Optional — restrict to preview only — Cloudflare Pages supports access policies (Cloudflare Access) to gate the site behind a login if you want docs to stay private

Open Questions

  • Do we want the docs site to be publicly accessible, or gated behind Cloudflare Access (free for up to 50 users)?

Status

live — https://fintrack-b3x.pages.dev