Docusaurus - I've been looking for you
I just wanted to build simple static site so I can publish something from time to time - I had no idea that it was not that easy in 2025.
TL;DR
When you want to generate simple blog, documentation or marketing site and you don't really care about the generic theme, you don't want to spend hours on configuration I encourage you to use Docusaurus.
It is super simple, battery included with easy learning curve.
You write Markdown and you get static HTML+CSS+JS which you can host anywhere.
Full thought process
Following text is not edited in any way - might cause you discomfort or you might fall asleep. Continue at your own risk.
When I quit my job this summer I realized that one of many things which I will miss will be the writing. Not the writing of code or documentation (ha-ha) but writing stuff for my colleagues.
I was used to write various tutorials or How to's but now I don't have audience. I believe I won't have much of an audience in the online blog world but that is not that important for me. Most important part is to put it down - somewhere where I can find it later when I need it.
I decided to publish this publically and I had pretty small list of requirements:
- tool needs to generate static sites (SSG - static site generator) - eg. HTML+CSS+JavaScript, no backend server needed
- I need to be able to create pages/posts in Markdown or MDX
- as I am very used to Github flavour of Markdown that would be nice as well
- needs to support code snippets - ideally with highlighting
- from time to time I want to add some images to my articles
- needs to be simple - for set up and maintenance
That's it. Not much. Or at least as I thought.
So I start searching for "static site generator 2025". The first article mentioned Astro, Eleventy, Hugo, SvelteKit and Next.js.
When I saw Astro, SvelteKit and Next.js I immediatelly thought of other React metaframeworks - Remix/React Router which I have already used in past and I liked the experience; TanStack Start - I am currently using TanStack Router on various projects and I am very happy with it; SolidJS and others.
I was intrigued in an idea that I might learn something while building my own personal site so I thought that I want to try them all. And I almost did.
I usually don't like the idea of overcomplicated frameworks like in my opinion Node.js is. As I see it all of the current React meta-frameworks are "just routers" with fancy compilator realized as Vite plugin. The functionality is always almost the same just the implementation and approach varies.
I like Svelte because it generates very little runtime JavaScript. I love Remix and it's simplicity and commitment to web standards and platform from the first day. I always wanted to try Astro and SolidJS but I feel like those are just other variations of what I've already seen.
What I didn't like for my SSG was need to deal with Vite and other tooling. Don't get me wrong, I think Vite is super simple in a terms of not getting into your way but I just think that this is too much for generating a few HTML pages.
So I tried Eleventy - unfortunatelly it only for some weird reason worked with Node.js v18 and v20 - I think I tried with v22 and there was some problem. Also I think that the project is great but I didn't want to waste time with setting up various plugins.
Hugo didn't work for me at all. I was very disappointed because when I heard it is written in Golang I wanted to see its performance (for my 2 articles a month).
Since I was frustrated that nothing just worked out of box and every framework/system was needed to be set up in some special way + most of the meta frameworks didn't really provided generation to static HTML and CSS but rather just prerendered and added bunch of useless JavaScript I did what every frustrated developer would do (or did at least one in his life since there are so many solutions) - I decided to write my own tool. How hard could it be?
All I need is one layout template, one index.ts where I define routes and one generate.ts which will dump React/MDX to static HTML with dynamically generated navigation.
I had some prototypes but none of that was easy nor fun. I throw them all. And I am very happy about that.
After good sleep and long pause I remembered that I have used Docusaurus in past - for generating the documentation. At the time it was v2 and it wasn't even set up by me but I remember writing in Markdown.
I tried to install it and run it and I instantly fell in love. It was everything I needed and more.
All the small features which I was thinking about when I was trying to set up my own solution were already there. If there was something which I didn't want I just needed to delete few files and few lines of configuration file - and I love to delete code!
I thought that I learn something new like Svelte or how to set up MDX properly or how to generate static site from dynamic routing... But I've learned much more. I've learned the lesson.
The lesson is not to reinvent the wheel and rather adapt to existing solution which is battle tested in production.
It might be that simple sometimes 🙂