Moving from Docusaurus to Hugo

For static generated sites I'm loving more everyday Hugo. It's speed and zero JavaScript dependency (unlike Gatsby) is just what the doctor ordered.

I have a private wiki for my, well, not public notes. The first version was done with WordPress (I even open sourced the theme). It worked okay, nice writing experience, one click publish/update. My problem with WordPress (and I do like WordPress) is security (of the PHP files, the database, etc) as well as maintenance of them. Plus in the end I just want to write plain text files.
I then moved to Docusaurus because I wanted to get rid of the database and increase speed (no cache plugins, no PHP cache, CPU load on each HTTP request to query the database and process the PHP files... Don't get me started!). Setup simplicity overall at the cost of writing experience.

Now, I'm about to change it again, to hopefully a even better setup. You tell me. My reasons? The same I had before. I want more simplicity and speed.

🤔 Why move to Hugo?

It's pointless to compare the size of the two systems. Hugo, running in Go and installed globally on your machine vs hundreds if not thousands of NPM packages with Docusaurus. It's a far cry from a simple HTML and CSS file we used back in the good ol' days.

My pain points:

• Dependency maintenance: I hate having to maintain NPM dependencies, because of security reasons or when I want to update to latest versions/features. You end up with a big package.json (and even bigger node_modules folder) that sometimes takes puzzle work to match dependencies with NodeJS and NPM versions, without breaking a feature.
  With Hugo, if it works, you don't ever need to update the Hugo binaries. Just build the site, it works and it's fast, like really fast.
• Build speed: might not be a fair comparison as the final generated product is different, but it's important to illustrate my use case.
  • Local macOS:
    • Docusaurus:
      • Develop: 8 seconds
      • Production: 23 seconds
    • Hugo:
      • Develop: 1 second
      • Production: 1 second
  • On GitHub Actions, build for production:
    • Docusaurus: average of 1.5 minutes.
    • Hugo: 45 seconds.

📝 Content

🗂 Categories

Docusaurus handles post categories with a _category_.json which has a content similar to:

{
  "label": "🎸 Guitar",
  "collapsed": true
}Code language: JSON / JSON with Comments (json)

This need to go. With Hugo you create a _index.md file under the folder. I like this better because with this file you can already include content for the category, before creating the child pages under it. You end up with something like:

/content/guitar/_index.md
/content/guitar/songs.md

📄 Pages

Regarding your content, your Markdown files, the "only" change is to add Front Matter to each .md file

I didn't have many files so I did it manually but on a high content site you might need a bash script or similar to automate the process. This would be the bare minimum:

---
title: Hello World
---

🏎 The need for speed?

With Hugo, as mentioned, you have full control over what JS and CSS you include in your theme.

Why not use PostCSS to remove unused CSS from your theme? 😁

👨‍💻 Conclusion

The move was quite painless. Since you'r content is practically the same, Markdown files, you can easily switch to another CMS if needed.

The most work, as you can imagine, is creating a theme in the new system. Less work if you get an open sourced theme, I forked one and stripped down everything I didn't need to make it lean.

I'm sure there are plenty of valid use cases for Docusaurus, it's actively developed and it looks promising. For my particular simple use case, I didn't need the added complexity (even if they claim: "Build optimized websites quickly, focus on your content").

What's your take? Which one do you use? What's your use case?