November 1, 2021

Why I Switched to a Static Site Generator

Last year, I converted all of my WordPress (and Basileus) sites to a static site generator called Eleventy (11ty).

Simpler Workflow for Me (and Any Developer)

As a developer, I spend a ton of time in Visual Studio Code, all of my code lives in GitHub, and most of my hosting is done through AWS. VS Code can spell check for me, GitHub Actions can automatically compress my images and build/deploy my website to AWS.

It took a little configuration in one project (then copied over to other projects) to automatically deploy my static site every time I make push my changes. As I see similarities between the projects, I can refactor the projects to share similar features between the sites (building a plugin in WordPress feels like overkill).

I don't need to worry about a database, I don't need to worry about usernames or passwords (less likely to get hacked).

Markdown is Fantastic for Content

Markdown has a small learning curve but it's something I was already familiar with -- it has crept its way into so many systems that a lot of technical people, including book authors, are likely familiar with it.

It introduces a design constraint that I love: Markdown has a fairly limited number of ways to format content. A simple template will account for most, if not all, reasonable output from Markdown and I can quickly build a stylesheet for the converted content. I can always fall back to HTML if I really need to handle an exception but it's almost always better to create a plugin for 11ty for common widgets (e.g. an inline related article card).

Markdown also encourages properly structured articles and makes it easy to see how headings (h1-h6) will impact article structure.

More Tools for Different Types of Content

WordPress is great for blogs (and other article based websites) but when I was using WordPress, I found I was adapting everything to fit WordPress's article/page model.

11ty has fantastic support for structured data. This allows me to be able to generate pages from JSON instead of creating individual articles/pages for similarly formatted content.

Derek Sivers has a Books I've Read page that works perfectly for this feature. I can build an array of data formatted like this:

    "title": "A Book Title",
    "author": "A.N. Author",
    "isbn": "1234567890",
    "readDate": 2021-01-01,
    "rating": 10,
    "imageUrl": "/static/books/example.jpg",
    "affiliateUrl": "//",
    "summary": "Lorem ipsum...",
    "notes": "Lorem ipsum...."

Then build a template to read the data and generate a static page for each item in the area (abbreviated example):

<h2>By: {author}</h2>
<p><img src="{imageUrl}" /></p>



This sort of thing is also incredible for displaying all of the cards in a Magic set, something Scryfall does incredibly and would be useful for Combat Math.

Possible Drawbacks?

This isn't a perfect solution and I'm sure I'll want to convert a few of the larger sites back to a web app. I don't have a reasonable way to put a paywall up for articles, authentication is kind of a pain, and I'll have to find services to handle things like contact forms or comments/reviews if I ever want to add visitor generated content to my site (probably not).

If I wanted a team to manage my website, it's a little limiting -- they'll need access to GitHub and be familiar with Node, git, and a few other tools to make changes to the site.

Site monitization is limited to advertisements, affiliate links, or services like Patreon. I'm better off collecting email address for a newletter at this point anyways.

Was 11ty this correct choice? Probably not. Most of the "appy" stuff I work on is Next.js and React so Gatsby is probably a better fit right now. I chose 11ty so I could decouple myself from React because I felt like my blog didn't need to be built on top of multiple frameworks. Hugo might have been a good choice if I programmed in Go, Jekyll if I was still spending time in Ruby. The same goes for VuePress and SvelteKit if I was using Vue or Svelte in my JavaScript projects.

For now, this works well for me and I'd encourage developer running a simple website to see if replacing WordPress with a static site generator would be a better option for them, too.