Building the Site

Last modified 1707278109000 ago by Wayne Starr

4 min read

Why?

When I set out to make a website for Lunch and Learns; I looked at using an existing static site generator (SSG). After a good amount of research (and general familiarity with the landscape), I ended up dissatisfied.

I wanted something that was:

There are a multitude of options, but I ended up not liking any of them:

I could have also built a bespoke solution in Svelte, but that seemed to be overengineering the problem.

At the end of the day all I really wanted was to take a directory of Markdown files and turn them into an educational website. So I decided to build my own simple SSG.

Inspiration and previous works

Many of the pieces of this project were inspired by other projects I’ve worked on or seen.

Back in my Air Force days I wrote a small PWA for templating configuration files. It was written in React and used mustache for templating, remark-gfm for parsing Markdown, and js-yaml for parsing YAML configuration files. I called it Config Composer.

As mentioned earlier, I use zola for my blog. I really like the simplicity of the layouts and the speed of the build process. This formed the basis for the layout of the project:

❯ tree . -I "node_modules|public"
.
├── README.md
├── bun.lockb            # lockfile for bun
├── content              # markdown files
├── generator/*.ts|mjs   # typescript build system
├── package.json
├── static               # static assets (images, manifest, etc)
├── tailwind.config.js   # tailwind config
├── templates            # html templates + css and TS entrypoints
└── tsconfig.json        # typescript compiler config

In college I made slide decks using reveal.js and hosting via GitHub pages. I actually would just submit the URL to the professor. Here’s a report on Gettysburg: https://noxsios.github.io/gettysburg/.

One of the final projects I wrote for Platform One was the documentation compiler that powers Big Bang’s docs (it’s still going strong 1+ years later!).

It was originally a side project that I was working on in my spare time, so the source code can actually be found on Github: bb-docs-compiler. The upstream repo is private, so I can’t link to it, and has some final changes + features that I never merged back into the public repo.

The compiler was written in Python and used mkdocs as the base SSG. I also used mkdocs-material as the theme, and mkdocs-git-revision-date-localized-plugin to show Git information in the docs.

More recently, I was looking at themes for Zola and came across adidoks. I really liked it’s use of minimal color, wide spacing, and clear typography. I used it as inspiration for the web layout of this site.

Honorable mentions:

Core features