Skip to main content

Why I Built This Portfolio with Docusaurus

· 4 min read
Carlos Carvajal Vázquez
Carlos Carvajal Vázquez
Full Stack | Senior Engineer

When I first decided to build my personal portfolio, my initial instinct was to go with a stack I was already comfortable with: Next.js for the framework and PrimeFlex for layout and styling. It felt like a natural choice. Modern, flexible, and powerful.

But as the project evolved, eI realized that what I actually needed from a portfolio website was different from what I typically build for products or applications.

This post is a quick look at that journey: starting with Next.js, what worked, what didn’t, and why I ultimately chose Docusaurus instead.

The First Attempt: Next.js + PrimeFlex​

My first version of the portfolio was built with Next.js and PrimeFlex. From a technical perspective, the setup made a lot of sense.

Next.js gave me:

  • Server-side rendering
  • Flexible routing
  • Strong React ecosystem
  • Full control over the UI and components

And PrimeFlex provided a responsive grid system and utility classes that made layout work straightforward.

For building applications or dashboards, this combination works extremely well. But once I started shaping the portfolio into something more than just a landing page, I began to notice a few challenges.

The Hidden Cost of Flexibility​

When you build with a general-purpose framework like Next.js, you get complete control but that also means you need to build a lot of things yourself.

For a portfolio that includes:

  • Project documentation
  • Technical blog posts
  • Structured content
  • Long-term maintainability

I quickly found myself re-implementing features that are already solved problems.

Things like:

  • Content organization
  • Markdown support
  • Navigation between documentation pages
  • A clean blog structure
  • Code block formatting
  • Versionable content

None of these are difficult individually, but together they add a surprising amount of overhead.

At that point, the portfolio was slowly turning into a mini content platform.

Rethinking the Goal​

The goal of this site isn’t to showcase my ability to build another React application.

Instead, it should:

  • Present projects clearly
  • Allow deeper technical documentation
  • Support a blog for engineering notes
  • Stay simple to maintain over time

In other words, I needed something closer to a developer documentation platform than a traditional web app.

That’s when I started looking at Docusaurus.

Why Docusaurus Made More Sense​

Docusaurus is designed around documentation-first content, which turned out to be exactly what I needed.

Out of the box it provides:

  • Markdown-based documentation
  • A built-in blog
  • Automatic navigation generation
  • Syntax highlighting
  • Static site generation
  • Versionable content
  • Great developer experience

Instead of building a system to host content, I could focus directly on the content itself.

Another major advantage is that each project can now have its own documentation page. Instead of describing projects in a short card or paragraph, I can write deeper case studies: architecture decisions, technical challenges, and implementation details.

For an engineering portfolio, that level of detail matters.

A Better Structure for an Engineering Portfolio​

With Docusaurus, the structure of the site became much clearer.

The main page focuses on the overview:

  • Experience
  • Areas of expertise
  • Selected projects
  • Education
  • Contact

Then each project can expand into full documentation pages.

And this blog becomes a place to share:

  • technical ideas
  • lessons learned
  • design decisions
  • experiments

It’s a much better fit for the kind of content engineers tend to produce.

The Final Result​

The stack behind this portfolio is now:

  • Docusaurus for the site framework
  • React components for custom sections
  • Markdown for documentation and blog posts
  • Static generation for performance and simplicity

It’s a setup that keeps the site lightweight, easy to extend, and focused on what really matters: sharing work and ideas.

Closing Thoughts​

Sometimes the best technical decision isn’t choosing the most powerful tool, it’s choosing the one that solves the actual problem you’re trying to address.

Next.js is fantastic for building applications. But for a portfolio that mixes projects, documentation, and writing, Docusaurus turned out to be a better foundation.

If you’re building a developer portfolio that includes technical write-ups or case studies, it’s definitely a tool worth considering.

And if you’re curious, feel free to explore the rest of the site.