Skip to content

Session Notes: erdscribe Blog Deployment (2026-02-12)

What happened

Turned the Obsidian vault at /Users/dydo/Documents/knowledge/vault/ (33 markdown notes, 5 folders) into a personal blog using Zensical + Cloudflare Pages at blog.erdscribe.com.

Issues encountered

1. Zensical PyPI squatting

  • System Python 3.9.6 installed zensical-0.0.2 (1.0 kB placeholder package, not the real thing)
  • Fix: Use Homebrew Python 3.11 → gets real zensical-0.0.23 (12.1 MB with Rust binary)

2. Zensical build doesn't output theme assets

  • zensical build generates HTML but does NOT copy theme CSS/JS/images to site/
  • Assets live inside the Python package at zensical/templates/assets/
  • Without them, the site renders as unstyled HTML with giant SVG icons
  • Fix: Post-build Python script copies assets from package dir to site/assets/

3. Wrangler "0 files uploaded" in Claude Code agent mode

  • Local npx wrangler pages deploy site consistently reports "Uploaded 0 files (0.42 sec)"
  • Debug telemetry revealed "hasAssets":false and "agent":"claude-code"
  • Even with cache-busted files (unique hashes), still 0/0
  • Even on a freshly created project with no prior deploys, still 0/0
  • Same command works perfectly in GitHub Actions (uploaded 53 files)
  • Root cause unknown — likely a wrangler bug in non-interactive/agent mode
  • Workaround: Use GitHub Actions for all deploys, never deploy locally

4. Project delete/recreate invalidates GH Actions deploys

  • Deleted the Pages project to try fresh, then recreated with same name
  • GH Actions runs from before deletion targeted the old project ID
  • New project has same name but different internal ID
  • Fix: Must trigger a new GH Actions run after recreating

5. Custom CSS not in deploy workflow

  • stylesheets/ebook.css was referenced in HTML but not copied to site/
  • GH Actions workflow only copied theme assets, missed custom CSS
  • Fix: Added shutil.copytree('stylesheets', 'site/stylesheets') to the workflow

Timeline

  1. Explored vault structure, normalized 27 files from inline bold metadata to YAML frontmatter
  2. Created section index pages, homepage with hero + card grid
  3. Configured zensical.toml with modern theme
  4. Hit Python 3.9 / squatted package issue → fixed with Homebrew Python 3.11
  5. Built locally, deployed to Cloudflare Pages via wrangler
  6. User reported mobile screenshots showing unstyled site (giant SVGs, raw markdown)
  7. Discovered theme assets missing from build output
  8. Wrote post-build copy script, but wrangler wouldn't upload files locally
  9. Spent ~1 hour debugging wrangler "0 files uploaded" — tried cache busting, project recreation, API direct upload, debug logging
  10. Realized GH Actions wrangler works fine → committed workflow fix → triggered fresh deploy
  11. All 53 files uploaded, site fully working
  12. Re-added custom domain blog.erdscribe.com

Key files

  • zensical.toml — Zensical config (Merriweather font, custom colors, ebook.css)
  • stylesheets/ebook.css — Custom ebook-style CSS
  • index.md — Homepage with centered hero + CSS grid cards
  • .github/workflows/deploy.yml — Auto-deploy workflow
  • requirements.txt — zensical>=0.0.23

What's working now

  • Auto-deploy: write in Obsidian → obsidian-git pushes → GH Actions builds → CF Pages deploys
  • blog.erdscribe.com serves styled content with ebook theme
  • Theme CSS, custom CSS, JS, search all load correctly
  • Dark mode toggle works
  • Mobile responsive (CSS grid + Zensical modern theme RWD)