Why I built my own static site generator (yakkomajuri.github.io)

I have built 2 SSG's over the years, once in 2009 and one this year. So it's fun to read through someone's internal thought process on their motivations and decisions.

Someone put together this mega list of 460 SSGs that I found helpful for inspiration and learning: https://staticsitegenerators.net/. Also would be a good place to add Teeny, though not sure if they are still updating the actual website.

My most recent attempt to rekindle my old blog turned into a write-a-SSG-that-can-import-tumblr and then a quest to recapture the nostalgic MySpace/text-mode feel, and no actual new blog entries.

Writing an SSG was procrastination at its finest. I did manage to migrate to ghpages and make the old tumblr and google-sites versions auto-redirect.

It was great when I started. I did some teaching back then and put my lectures in its own section, which I could re-build and serve to the local network for my students.

I no longer know how it works. I don't care to maintain it. It needs big changes to handle something like embedding a Jupyter notebook. And it depends on Python 2.6(!).

With hundreds of pages, and its own custom URL layout that I don't want to break, I dread migrating to a modern system.

It’s a little bit of a strange tool, but you can start by pointing it at an HTML file, and it will automatically build it, bundling and minifying any dependent resources and giving them a hashed filename for better caching.

If you want to do multiple pages, it’s simple; you can just link them. Parcel Bundler will pull the links and bundle them just like the first page, recursively. When it generates linked pages, it won’t make a hashed filename, so your directory structure will be left in-tact. If you want nice subdir pages, you can put index.html files into subdirectories, and voila. And as a bonus, any resources you depend on from two different pages will share the same bundled resource, as you would probably hope.

But HTML can get repetitive, so you probably want templating of some sort. For that, I tend to rely on Pug templates. They support blocks and template inheritance, so now you can do more advanced stuff without having to repeat yourself constantly.

Finally, if you wanted to use TypeScript or SCSS, you just, can. They will be compiled and bundled to JS and CSS transparently, exactly like you would probably hope.

And then maybe you want to do something more interesting than what it can do out of the box. Like for example, maybe you want to render Markdown files into a template (obviously relevant to this use case.) In that case, you can extend Parcel. My favorite shameless plug is a documentation site I have set up for a reverse engineering project which uses Parcel to render Markdown and Kaitai Struct files into templates which are interlinked with each-other. The resulting site is fully static and the build process is relatively quick. I don’t know of any cleaner way to do something like this!

https://packets.pangdox.com/

The biggest downside of Parcel is that I did, in fact, need a custom plugin to render Markdown files directly into templates. Maybe there’s a simpler way or a plugin on NPM that serves this relatively common use case. But I just love having the page graph intertwined with the asset graph like this; it’s super powerful for building fully static websites. The only thing it feels weak for is if you want to generate pages from data somehow; Parcel is pretty tethered to pages being an asset, so as far as I know you can’t simply synthesize them. Still, despite this and other quirks, I really do enjoy the experience.

I've written my own static site generators before, too, and with all static site generators pretty much, I’ve felt unsatisfied with how they interacted with bundlers and compilers.

    all: $(addprefix $(OUTDIR)/, $(addsuffix .html, $(PAGES))) $(addprefix $(OUTDIR)/, $(notdir $(wildcard imgs/*)))  $(OUTDIR)/styles.css 

    $(OUTDIR)/%: imgs/% | $(OUTDIR)
        ln $< $@

    $(OUTDIR)/%.html: pages/%.page template | $(OUTDIR)
        $(BUILDER) template $< $@

    $(OUTDIR)/styles.css: styles.css
        ln $< $@ 

    deploy: 
       rsync -avh $(OUTDIR)/ $(DEST)

My deploy script (it's just 5-10 lines of bash) mostly for some of my "old" angularjs(yes v1)

1) merge all js files (cat file.js >> app.js)

2) make sure any files that request/include JS and HTML files are not cached (generate new random ?rcc=random-num)

    find -type  f  | egrep  "html|js" | xargs sed -Ei s/"rcc=([0-9]+)"/rcc=$RANDOM/g

Sexy ? Absolutely not , does it work ? Like a dream :)

Having the ability to just type "./deploy-aws.sh" and be done in 5 sec is an amazing ability to have for you project. Especially if you are SOLO founder.

I don't completely agree about Jekyll (it can be very light weight, requiring zero Ruby unless you need to extend things), but rolling your own solution for a personal home page is always nice.

https://git.sr.ht/~evan-hoose/SSSSS

Is it garbage? Yes. But it's my garbage, and does what I need it to!

You can actually make your own themes with github pages

https://www.11ty.dev/

What I like about 11ty is that it comes with several template languages out of the box and you can pick whatever you want. You can also mix several languages.

Or you can run it in a bare-bones minimal version. I guess it just fits my mental model.

Furthermore, it doesn’t have constant updates. The API is quite stable (although 1.0 will be released soon, which requires some manual work). But I haven’t had to change a thing in a couple years.

Not affiliated, just happy with it.

- because I've done it already and I haven't gained anything from it other than feeding my ego

- it makes me work on keeping it updated to "my custom needs" more than I work on the actual project that needs it

- it always gets outdated really fast, esp if it uses js a lot

- I've learned that it's generally a waste of time, time better spent on other areas of your business and existing tools are good enough

    ---
    template: custom.html
    ---

    # My normal markdown

    import fm from "front-matter";

    const data = await fs.readFile(...);
    const { attributes, body } = await fm(data);
    // attributes: { template: "custom.html" }
    // body: "# My normal markdown ..."

[2] https://www.npmjs.com/package/front-matter

[1] https://www.project-daily.com/pages/an-experiment_1065.html

Thanks to a custom build with kotlinxhtml and a bunch of other tools, I'm very efficient. High performance thanks to simple html+css and a little vanilla js, so the pages show up instantly with 38k+ monthly visitors on a low-spec cheap server. No background loading or rendering in js or whatever.

Sure it’s not customizable at all: it can only generate my site. And that’s fine. I like it that way.

For example: I sometimes translate poetry, and I have a bunch of code that renders individual poems from plaintext (not Markdown, because newlines and whitespace _are_ significant): https://github.com/nathell/nhp/blob/master/src/nhp/poems.clj