Skip to content

Build the Learning Journal

What I built

A Git-backed markdown site at learn.logiudice.me with:

  • mkdocs-material — dark/light mode, search, tags, git revision dates
  • Python aggregator (scripts/aggregate.py) — reads build note frontmatter, regenerates dashboard and skills map automatically
  • Scaffold tool (scripts/new.py) — creates new guide or build notes with consistent frontmatter
  • GitHub Actions CI/CD — runs aggregator, builds site, deploys to Cloudflare Pages on every push to main

Architecture

learning-journal/
├── docs/
│   ├── index.md                 # Landing page
│   ├── 00-Dashboard.md          # GENERATED
│   ├── Skills-Map.md            # GENERATED
│   ├── guides/                  # Hand-written project briefs
│   ├── builds/                  # Completed build notes (frontmatter source)
│   ├── cert-progress/           # AZ-104 and AWS SAA checklists
│   └── troubleshooting/         # Problems solved
├── scripts/
│   ├── aggregate.py             # Regenerates auto-generated docs
│   └── new.py                   # Scaffold for new notes
├── .github/workflows/
│   └── deploy.yml
├── mkdocs.yml
└── requirements.txt

Key decision: build in Actions, not in Cloudflare Pages

mkdocs-git-revision-date-localized requires full git history. Cloudflare Pages does a shallow clone and the plugin fails. Fix: build in GitHub Actions with fetch-depth: 0, deploy the built site/ folder via Wrangler. This also allows running aggregate.py as a pre-build step.

What I learned

  • mkdocs-material configuration and plugin ecosystem
  • Python frontmatter library for reading YAML frontmatter from markdown
  • GitHub Actions: pip caching, full git checkout, secrets
  • Cloudflare Pages deployment via Wrangler in CI/CD