Why I Migrated to Docusaurus

Okay, story time. When I started blogging, I did what every over-confident undergrad student does: I built my site from scratch.

I used Next.js for SSG (Static Site Generation). I wanted to flex my ability and prove I could build something with my own two hands. And ngl, it was cool at first. It was mine.

But It was too basic. I was stuck with plain markdown (even tho I've configured MDX). No fancy components, no diagrams, no copy-paste buttons on code blocks. Just text on a screen.

The Breaking point​

I realized I was caught in a loop. I'd have a great idea for a post, but then I'd think, "Man, this needs an interactive chart."

On my old site, that meant:

1. Stopping the writing process
2. Opening VS Code
3. Installing some random npm package
4. Debugging dependencies that failed to work for 3 hours
5. Maybe writing the actual post (if I wasn't too tired)

In my opinion, if you're spending more time maintaining your site framework than actually writing posts, you're doing it wrong. And I'm wrong, don't be like me.

I needed something that was ready to go out-of-the-box to stop me from being a maintainer and actually post something to reorganize my thoughts.

I went down the rabbit hole looking for alternatives. I checked out Hugo (fast but minimal), Astro (ngl very dope, but felt like overkill for this), and a bunch of others like 11ty and VitePress.

They're all great, seriously. But I kept coming back to one principle: YAGNI.

You Ain't Gonna Need It.

I didn't need a framework that could juggle five different UI libraries. I just needed a really solid documentation/blog site.

Why Docusaurus​

I landed on Docusaurus (v3). It’s open-source from Meta, and it honestly had everything I was trying to build manually.

1. MDX out-of-the-box

This is the big one. I can write standard markdown, but import React components directly into the post. I do implement MDX in my old site, but I spent days on it while MDX support is came built-in. But other frameworks (like Astro) also have it officially integrated, so there are multiple options.

2. The features I actually need

Things I dreaded building from scratch are just... there. Code blocks with syntax highlighting and copy buttons are built-in. Admonitions: You know, these colorful boxes I'm using? They come standard. It also has Mermaid.js support out of the box.

3. A purpose-built Content Engine

Unlike Next.js, where I'd have to parse Markdown and build my own routing logic, Docusaurus creates a content-aware SPA automatically. It scans my files to auto-generate the navigation tree, handles SEO metadata for every page, and creates a "docs-specific" routing system (like /docs/v1/intro) instantly. It’s a specialized tool, not just a generic framework.

The migration was a joke (in a good way)​

I was bracing myself for a week of pain. It took me like two hours, tops.

Here is literally all I did:

npx create-docusaurus@latest my-new-blog classic

Then I customized docusaurus.config.js with my info, dragged my old markdown files into the blog/ folder, and spent a not-so-little time tweaking the themes.

Final thoughts​

Writing tests for my weird, custom-built Next.js blog was a major pain in the ass. With Docusaurus, I'm trusting a production-ready project maintained by people way smarter than me. I don't need to test the framework anymore.

So yeah, it's good to be writing again.