Skip to main content

Making a Docusaurus site

· 3 min read
Zack Gomez
Zack Gomez
Local nerd

Coding a static site​

This project originated from my desire have a website. My criteria were:

  • Don't use Wordpress
  • Show my ability to execute simple, elegant code with function before form

I started by coding a website from scratch with HTML and CSS. Learning to lay out the page with nested divs and flexbox styling was fun but time-consuming. Starting without a sketch was a mistake. But rapid iteration drilled the key concepts quickly.

Why use an SSG?​

Working with raw CSS, page layout was an enjoyable time-suck. But I don't want a blog post to take an hour. When I contemplated adding functionality - photo galleries, richer blog experiences, etc - the granular control of coding from scratch started to feel more limiting than empowering. I'm not looking to start a career as a web developer here.

Markdown​

Several months later my coworker Ben got me into note-taking with Obsidian, which opened my eyes to Markdown. It's efficient, widely interoperable and elegant. I love it.

This website is generated using Docusaurus, a static site generator built on Node.js. It and similar SSGs are intended for code and project documentation sites.

Choosing Docusaurus​

How did I get here?

Jekyll, Hugo and other options​

A while back I did a freeCodeCamp.org API development course on YouTube. It got into SQLAlchemy, Pydantic, Postgres and all sorts of fun stuff. Playing around in this world opened my eyes to static site generation with Python and JS tooling.

Jekyll and Hugo are two very popular options. I haven't tried either yet!

MkDocs​

Before settling on Docusaurus I tried Material for MkDocs. It supports blogging as of a recent (2024-2025ish) update, but some functionality is still in the oven. MkDocs relies on community modules for a lot of functionality.

Compared to Docusaurus I found it substantially more elegant to work with, and its documentation and community support is more robust. I'd definitely recommend you give it a try - there's a good chance you'll vibe with it over Docusaurus.

Dokuwiki​

I've also used Dokuwiki for a locally hosted server in a little Apache LXC on Proxmox. Since getting into Markdown I've lost interest in maintaining that and my homelab documentation is all moving to Obsidian. But Doku is a great platform - it's good-looking and functional and easy to work with.

So I'm happy with Docusaurus?​

As I'm typing this, yes. I love the following:

  • Easy, native image colocation in blog post directories with no mucking about
  • It's very pretty
  • Blog features are rich and "just work"
  • Default layout aligns with my preferences

Building the site​

Docusaurus' documentation is good. For a dev with my level of experience (so like, not an actual dev), there are some gotchas. I got stuck on the following:

  • Deciding whether to use GitHub Pages or Cloudflare Workers/Pages to serve my site

I landed on Cloudflare because I like keeping my web admin stuff in one place, and because I'm using a static site generator I don't care about showing off my code.