Skip to main content

zackgomez.net

This website is built with Docusaurus.
If you want to build a site like this, read on!

info

This article was written in August 2025 and may be out of date by the time you get here. Consult the latest documentation available from the respective developers. Site version at time of writing was Docusaurus 3.8.1.

warning

This article is written for beginners, but expects you to be familiar with fundamental concepts and abbreviations.

Quick reference & tooling​

Framework​

CI/CD + web hosting​

note

This combination of tools allows you to push your build directory straight to Cloudflare for hosting. Unless you prefer GitHub Pages, want to show your source code, or need to work collaboratively, you don't need to use GitHub. I push the repository to GitHub separately to allow for version control and to track my contributions, but don't link GitHub and Cloudflare at the time of writing.

Basic questions​

What is it, how does it work, why might you want it?

Why not code from scratch?​

Try it! If you want a mostly-text site with two or three HTML pages and some light CSS that you update a couple times a year, serving direct source files is going to work great.

I started by coding a static page. I worked for around 80 hours and got a great crash course in practical HTML and CSS. But then I decided that I wanted a blog, not just a place to stick my resume, and I wanted a photo portfolio, not just a subdomain linked to a 3rd-party host.

Staring down the barrel of scope creep, a few things became clear to me.

  • I'm working 12-14 hours a day already
  • My ambitions do not include becoming a web developer
  • I want to spend my time writing, not making paper from scratch

And as soon as I got comfortable with Obsidian for personal note-taking, I wanted to do everything in Markdown.

What is Docusaurus?​

Docusaurus is a static site generator. You write content and functionality in Markdown, MDX, HTML and other languages. It compiles your source code into static webpages once (at "build time"), and you place that build on a web server.

Static vs dynamic sites​

Modern web development may encompass a site that serves both static and dynamic content, so the line can be blurry. The practical distinction is this:

Static pages are fast, efficient, flexible and suitable for most common use cases. Dynamic pages provide deeper functionality at the cost of complexity.

From Wikipedia:

A static web page, sometimes called a flat page or a stationary page, is a web page that is delivered to a web browser exactly as stored.

Dynamic webpages are parsed by the server upon request. The server may interact with a database or other lower-level system to present content, or modify it for the client.

Static doesn't mean boring. Content served on static webpages can be dynamic in the classical sense of motion, action, and interactivity.

Building this site​

If you follow the recipe you should end up with a site that looks mostly like this one.

Bootstrap your environment​

Install an IDE​

You need an editing environment. Download VS Code, Emacs, Eclipse, or whatever you're comfortable with.

Install extensions (VS Code)​

I'm on VS Code and if you are too, I'd grab the following extension modules:

  • ESLint
  • MDX
  • YAML

Now you have syntax highlighting everywhere you need it.

Install the framework​

You need libraries and frameworks.

  • Install Node.js with npm
  • Install Docusaurus
  • Install docusaurus-plugin-sass
  • Install lightGallery

Initialize Docusaurus​

  • npx create-docusaurus@latest my-website classic
  • cd my-website
  • npm start
Embedded developer documentation

Create content for the site​

I did trial-and-error until I figured it out. You'll likely change your mind about where stuff goes.

Docs​

Docs go in /docs and subdirectories. You can write in .md, .mdx, .js, etc with inline or modular CSS, however you prefer. You can call lots of premade variables and classes from Docusaurus. Within each doc directory, use a _category_.json file to define basic attributes, like:

/docs/cars/_category_.json
{
  "label": "Cars",
    "position": 1,
    "link": {
    "type": "generated-index",
    "description": "A repository for automotive work"
  }
}

Alter or remove the position value to place the category in a specific rank, or to allow it to default (alphanumeric sorting). Within each individual object you can also define attributes. Whatever your H1 is will supersede the file name. If no H1 is given, the file name will become the heading.

Components have to be imported below the MDX attributes, the MDX will not be parsed if it's not the first thing on the page.

This page, for example:

/docs/site.mdx
---
sidebar_position: 2
---

# zackgomez.net

import { Spotify } from 'react-spotify-embed';

Pages​

Pages you place here will be built into the site root. My About page is located in the source at /pages/about.js and builds to zackgomez.net/about.

Static​

So far I've only used this directory for sitewide-accessible images. For docs, I use a subdirectory (/docs/cars/img) to contain images relevant only to that category.

Source​

Components go here. You can build them, export them and call them like import HomepageAbout from '@site/src/components/HomepageAbout';. As long as you don't mess around too much with docusaurus.config.js you should be able to use @site as an alias or pointer for the project root.

Set up Cloudflare​

Not written yet!

Install Wrangler​

Not written yet!

Configure Docusaurus​

Refer to the Docusaurus setup guide, it's pretty good. You may find the project structure confusing at first due to the mix of different file types and linking.

The knobs and switches are mostly in @site/docusaurus.config.js. \

Start by renaming some defaults, like the site's name.

Learn a little React​

note

This anchor section is under construction as I learn a little React.

Spotify applet​

I thought "it'd be cool to have a track of the day thing!" so I Googled "react spotify embed". Turns out there's an NPM module called react-spotify-embed. Takes some of the mystery out, doesn't it?

npm install react-spotify-embed


import { Spotify } from 'react-spotify-embed';

<Spotify wide link="[link to track, album, etc]" />

Make lightGallery work​

note

This anchor section is under construction as I figure out how to make lightGallery work.
Check back later!

Publish the site​

npm run deploy will do the job in one shot if you've hooked up Wrangler correctly. Usually I do a git add, commit and push before deploying the latest version. Sometimes there will be multiple commits between deployments.