Execution Plan: Portfolio v1 + GitHub-First Workflow

Summary

Create a GitHub repository first, then build v1 on a dedicated feature branch with small regular commits.

v1 scope:

  • Pages: Home, Blog, About, Now
  • No projects section/routes/content yet
  • Hudovich-inspired minimalist look and spacing
  • Geist + Geist Mono typography
  • Hero intro with temporary avatar slot (later replaced)
  • No hero CTA, footer contact only
  • Plausible enabled, Giscus deferred
  • Light default + dark toggle
  • Netlify-ready

Repository and Commit Workflow

  1. Initialize local repository in the project directory.
  2. Configure local git author (use a non-identifying identity if desired).
  3. Create initial commit on main with repo bootstrap files.
  4. Create GitHub repo (name TBD), set origin, push main.
  5. Create working branch codex/portfolio-v1 (prefix requirement satisfied).
  6. Implement in small commits (one logical unit per commit), pushing regularly to origin/codex/portfolio-v1.
  7. Final integration is merged back to main after validation.

Planned Commit Checkpoints

  1. chore: initialize hugo site and base repository files
  2. feat: add base layout, metadata partials, and top navigation
  3. feat: implement home page structure and hero avatar slot
  4. feat: add blog list and blog single templates
  5. feat: add tags taxonomy pages and blog pagination
  6. feat: add about and now pages
  7. feat: implement hudovich-inspired typography and base visual system
  8. feat: add light/dark mode toggle with persisted preference
  9. chore: add plausible analytics integration
  10. chore: add netlify configuration and production polish
  11. docs: add content editing and deployment notes

Public Interfaces / Content Contracts

Routes

  • /
  • /blog/
  • /blog/<slug>/
  • /tags/<tag>/
  • /about/
  • /now/
  • /index.xml (RSS)

Content Files

  • content/blog/*.md
  • content/about/_index.md
  • content/now/_index.md

Blog Front Matter Keys

  • title
  • date
  • lastmod
  • summary
  • tags
  • draft
  • cover

Hugo Params (hugo.toml)

  • author.name
  • author.email
  • author.tagline
  • analytics.plausible_domain
  • theme.default_mode = "light"

Implementation Steps

  1. Scaffold Hugo project and base config (hugo.toml) with blog tags, RSS, and pagination.
  2. Build shared template foundation in layouts/_default/baseof.html and partials for head, nav, footer, and theme script.
  3. Implement home template with:
    • Intro text block
    • Temporary avatar image block
    • About snippet block
    • Latest blog posts block
    • Footer links with subtle contact
  4. Implement blog list and single templates plus tag archive templates.
  5. Implement about and now page templates.
  6. Add CSS system in assets/css/:
    • Geist / Geist Mono usage
    • Weight scale aligned to selected reference feel
    • Minimalist spacing, borders, muted palette
    • Mobile-first responsive behavior
  7. Add dark toggle JavaScript with localStorage persistence.
  8. Add conditional Plausible partial that loads only when domain param is set.
  9. Add netlify.toml for build, publish, and deploy behavior.
  10. Seed placeholder copy and posts for structural validation.

Testing and Acceptance Criteria

  • hugo --minify passes cleanly.
  • All v1 routes render correctly and navigation links work.
  • Blog pagination works across multiple pages.
  • Tag pages generate for tagged posts.
  • RSS endpoint is generated.
  • Dark toggle persists across refresh and page changes.
  • Plausible script appears only when configured.
  • No projects route, navigation, or content artifacts exist.
  • Layout is stable on mobile and desktop.

Assumptions and Defaults

  • Work happens on codex/portfolio-v1 with frequent small commits.
  • Projects section is intentionally excluded from v1 code.
  • Temporary avatar is used until a final image is provided.
  • Contact remains footer-only, with no dedicated contact page in navigation.