List of Static Site Generators I've Used

A very, very long time ago I love deploying web servers like Apache and Caddy on my own on VPS's and setting up HTTPS etc just for fun.

Yes, they're still fun, but this post is about converting more user friendly files to HTML files using static site generators so that I can be free of doing that.

The list below are some of the SSGs that I remember I used as time of writing, I remember some pretty good ones but

Blogs

Jekyll, My First SSG

Popularized by GitHub Pages. I remember choosing the hacker theme, and setting up the CNAME file, A records etc just to link a custom domain to my page.

I taught my friend V to use Jekyll. It took me a lot of time to figure out how to use it the first time, because I had to mess with bundler (part of Ruby's ecosystem), and I didn't know what build and serve meant.

I was very excited when I figured out how it works, and I tried so many themes and plugins.

I even cloned many docs repo of open source projects just to build them locally and was happy that it looks the same as the official site, but it was much faster since I was serving from my own compputer.

The famous Android custom ROM LineageOS uses Jekyll for their docs.

Hugo

I read the Manning's book on Hugo and I learned that the author of Hugo is some core Go / Docker dev.

Indeed very powerful and feature rich, but too complex for me.

And hand writing templates is not fun (I didn't find the ones I liked).

Too many obstacles to use it the way I want, and I gave up.

For power users who's an HTML/CSS, Go templating language, git submodules and taxonomy expert who have too much time, this is a wonderful and powerful tool. But telling users to use git submodules to install a basic theme in the quick start guide is going to drive people away! I know I'm not comfortable using submodules. And the basic theme is not presentable, I spent hours looking for a theme that's more to my taste and found none.

Google made the docsy theme (for documentation sites, used by Navidrome and many other projects) and got 5k stars. Themes definitely plays an important roles in how the generated sites will look, especially for Hugo and MkDocs.

Next.js

This site. Client-side navigation and pre-fetching.

Dev experience and build speed is meh. I don't preview my new posts anymore because it's just so, so slow (and I'm using bun).

Someone please rewrite everything in Rust!

knitr, rMarkdown

I'm a fan of Yihui and his website, and I've gone through most of his blog posts and used many wonderful tools he made.

https://yihui.org/knitr/

According to his site, he's the first one who made something that converts a doc with text and code (which will be run) into a pretty document.

There's also blogdown, bookdown and a bunch of other *down projects.

Quarto

Claims to be rmarkdown's successor.

md, rmd, ipynb -> HTML / PDF

Uses knitr internally.

Obvervable Framework

A new one.

I tried it and like it, I'll make sites using if if I learned how to use Observable Plot the right way.

Other JS Based SSGs

• Gatsby: Very bad expreience, spent so much time messing with the image plugin because some npm module just doens't work on my computer.
• Hexo: Many Mandarin sites use this, I associate the site owners with technical competancy. I didn't try this.

Other Non-JS Based SSGs

• Pelican: Python based. Not very impressive
• Python based CMS's, some built with Django, some converts Jupyter notebooks to HTML
• Rust based: Zola etc, I don't see good reasons to use them instead of Hugo
• I tried some bash / awk based SSG and I love the concept!

Docs

• Sphinx: rst -> html; Python docstring -> HTML
  • Pain in the ass to work with. Wasted a lot of time messing with 1000 config options and the auto-generated module docs from docstrings and plugins and automated builds when I worked on EasyGraph.
  • The init process generates an obsecure Makefile that's limited in what it can do, and sometimes what gets rebuilt is not clear and you need to make clean and build from scratch again.
• MkDocs: md -> html; versatile
  • FastAPI and tiangolo's other doc sites use this
  • Supports callouts / admonition; highlighting certain lines in codeblocks
  • Everyone uses the material design theme
• Docusaurus: md / mdx -> html; client-side navigation; many plugins; limited theming options
  • https://rick-n-morty.teddysc.me (default theme with custom color scheme and homepage)
  • I have ~5 other private sites built with this
    • Note taking: https://misc.teddysc.me (private)
    • I scraped some sites and converted them to Docusaurus sites because I love the full text search and client-side navigation features.
• GitBook: this reminds me how old I am
• mdBook by rust-lang: Fast and sane defaults. Love it!
  • Doesn't force you to put specific files in a specific directory or in a specific way (like Hugo or many heavy JS frameworks).
  • https://llm-biases.teddysc.me

Notes

• Docusaurus, see above
• quartz: designed for Obsidian.md, md -> HTML, full text search works out of the box without configuration. Downside: to install the tool you need to clone their repo (as of 4/17/2024). I love it.

Web Apps

• Next / React, for Next, use the export to static site option
  • https://teddysc.me/random (web apps deployed on the same site as the blog)

Slides

• pandoc
  • S5 for simple pages - pandoc --self-contained -t s5 -s -V s5-url=/Users/tscp/testdir/pandoc-slides/s5-11/ui/default habits.txt -o s5-sc.html
  • reveal.js for more complex pages - pandoc --self-contained -t revealjs -s habits.txt -o habits.html
• Apple Keynote.app (closed source, proprietary, but there's an HTML export option; I guess this count as an cumbersome SSG since I need to do this for every file everytime I update them)
• JavaScript based markdown to fancy slides: reveal, remark, slidev. I feel they're too complicated for me so I decided not to use them unless necessary.

Standalone HTML Filse

pandoc.

• 404 Pages
  • https://404.teddysc.me/
  • https://s.teddysc.me/sljdflksjdklcjsdlkf
• When I just need simple HTML:
  • https://chatgpt.teddysc.me

Photo Gallery

dir structure -> HTML

https://gallery.teddysc.me (yes, this site is fully static so that I don't pay the hefty bill for traffic costs.)

The problem with this approach is the long build time in the CI because it has to process >1000 photos each time I make a small change or add a photo, generating thumbnails and more.

https://foto.teddysc.me (Be careful! Loading the page will download ~108 MB resources; slow because it tries to load everything at once; features a Best section at the top with my hand-picked photos.)

Building with foto for 1k photos takes ~2 minutes on a 32-core machine (my self-hosted GitHub Actions runner).

PITAs

• Any JS based SSG that eats up 800MB of your SSD (node_modules, .docusaurus, .contentlayer, build).
  On the other hand, mdBook is extremely clean and fast and takes up virtually no extra spaces, besides a few HTML files in the build dir.
• Extremely slow preview (Next) or build (Next, Sphinx)
• SSGs that make you want to kill yourself when using it (Sphinx)
• Some SSGs' websites make you want to kill yourself before even trying it (too much JS, slow and bloated / "I just don't want to show you how it works so here's a minimal example - it's that simple" (11ty) / too opinionated (we believe you need a dir for every set of slides, and one site should only contain one set of slides, if you don't like it then hack your own build shell script" (slidev)))
• Bad dependencies (Some JS SSGs, Gatsby plugins)
• Bad docs (Context: bun has been around for many years and gained huge popularity. Can I use bun? or is it npx only? Okay I tried both because you didn't document it)

See Also

https://jamstack.org/generators/