Why I Built My Portfolio with Markdown

The Power of Simplicity

When I decided to rebuild my portfolio, I had a choice: use a complex CMS, a database-driven solution, or embrace the simplicity of Markdown. I chose Markdown, and here’s why.

Inspiration from Industry Leaders

Lee Robinson’s migration of cursor.com from a CMS to raw code and Markdown was eye-opening. He completed what he estimated would take weeks in just three days. This demonstrated that:

• Markdown is fast - No database queries, no CMS overhead
• Content is portable - Plain text files that work anywhere
• Version control works perfectly - Git tracks every change
• It’s future-proof - Markdown will always be readable

Benefits I’ve Experienced

1. Speed

Static site generation means my portfolio loads instantly. No server-side rendering delays, no database queries. Just pure HTML served from a CDN.

2. Version Control

Every change to my content is tracked in Git. I can see exactly what changed, when, and why. Rolling back is trivial.

git log -- src/pages/index.md
git diff HEAD~1 src/pages/index.md

3. Writing Experience

I write in the same editor I code in. No context switching between a CMS admin panel and my IDE. Markdown syntax is natural and doesn’t get in the way.

4. Zero Maintenance

No CMS to update. No security patches. No database to maintain. Just static files deployed to Vercel.

The Blog Setup

Setting up a blog with Astro and Markdown is remarkably simple:

1. Create a src/pages/blog/ directory
2. Add .md files for each post
3. Create a layout for styling
4. Build an index page to list posts

That’s it. Astro handles the rest automatically.

Trade-offs

It’s not all perfect. Markdown-based sites have limitations:

• No dynamic content - Everything is pre-built at deploy time
• No real-time features - Comments require third-party services
• Manual media management - No upload interface like a CMS

But for a portfolio and technical blog? These trade-offs are worth it.

Conclusion

Building with Markdown aligns with how I already work as a developer. It’s fast, simple, and maintainable. Most importantly, it lets me focus on content instead of infrastructure.

If you’re a developer building a portfolio or blog, I highly recommend giving Markdown a try. You might be surprised at how liberating it feels.

What’s your experience with Markdown-based sites? Let me know on LinkedIn!