Building a Docusaurus site

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.

Mistakes aside, getting to rapidly iterate the site design with a live dev server was an incredible learning-by-doing tool. Trial and error can be the best way to drill fundamental concepts, especially with CSS.

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
• It’s a great way to dive into React.js

Building the site

Head over to my documentation page in order to read a full writeup on how this website is constructed. Learn from my mistakes!