GitHub as CMS: Modular, Effortless Developer Portfolio
Published: (February 2, 2026 at 01:27 AM EST)
2 min read
Source: Dev.to
Source: Dev.to
The Problem: Portfolio Rot
Managing and refreshing a portfolio can be time‑consuming. Many developers struggle with:
- Ongoing content updates
- Keeping visual assets in sync
- Preventing site breakage after changes
The Innovation: GitHub as a Headless CMS
- Content – Stored as local MDX files.
- Assets – Managed directly in the
public/folder, enabling real‑time GitHub previews. Next.js automatically optimizes images, removing the usual headaches of handling visuals. - Validation – Enforced by Velite; malformed data (e.g., missing project dates) causes the GitHub Action to fail the PR check, preventing broken builds.
Leveraging Google AI Tools
- Google Gemini Pro – Used for deep research, data analysis, and reporting. It helped identify common portfolio pain points and guided the selection of the technical stack, feasibility assessment, and risk mitigation.
- Google Antigravity agents – Integrated for additional automation (details omitted for brevity).
The Tech Stack
| Component | Technology |
|---|---|
| Framework | Next.js 16.1 (App Router) with React 19 |
| Styling | Tailwind CSS v4.1 – CSS‑first configuration, semantic variables for instant theming |
| Content Layer | Velite 0.1.8 + Zod for strict build‑time schema validation of MDX files |
| Deployment | Containerized via Docker, deployed to Google Cloud Run with a continuous deployment pipeline from GitHub |
The “Self‑Driving” Repository
GitHub itself acts as the CMS:
- Content and images are updated entirely through the GitHub Web UI.
- Safe updates (linters, type checks) are auto‑merged.
- Framework upgrades are flagged for manual review, ensuring the portfolio evolves without constant maintenance.
Composable LEGO Architecture
The site is built from modular “Blocks” (e.g., Hero, Gallery, Testimonials). All blocks are assembled in a single file (page.tsx), allowing endless rearrangement without touching complex code.
High‑Performance Visuals
- Lighthouse score consistently 98+.
- A custom MDX image interception component eliminates Cumulative Layout Shift (CLS), ensuring smooth, consistent rendering of uploaded images.
Technical Deep Dive
Thanks to Google AI for the motivation behind this refresh. The solution not only solves a personal pain point but also provides a reusable pattern for fellow developers seeking a low‑maintenance, high‑performance portfolio.