Migrating from Jekyll to Eleventy

Posted 2024-04-02 #this blog · #unfortunately, computers

Jekyll has been my preferred static site generator for the last 8 years, starting with my old simfiles page. Static sites are awesome; they require virtually no maintenance and they load as fast as your Internet connection will allow. You'd think that speed would carry over to the development side, but Jekyll somehow manages to spend nearly 30 seconds building this tiny website from a cold start! According to the Internet, there are exactly two reasons why this might happen, and I've apparently discovered an elusive third reason. I want working on this site to be fun, and the long startup time was eating into that, so it was time to finally search for something new.

Choosing how to choose

Picking a new framework is always the hardest step, no matter what the integration phase looks like. Having to make a choice that you know will influence how you spend most of a future weekend is just begging to be put off indefinitely. Fortunately, there are solid resources for this online, such as Jamstack's list of generators. Sifting through a pre-curated list of options lets me focus on finding the qualities that matter to me, rather than having to both curate and establish my criteria at the same time.

Perusing the most-starred options helped me identify a few important-to-me attributes of a static site generator:

  • I want to write dumb, templated HTML, not components in a JavaScript framework. I write React code for work, and when I use it in my hobby projects, it's generally for bigger websites that demand a tight integration between backend and frontend. Making meow.garden isn't my job, and it doesn't have a backend anyway.
    • This immediately rules out React-based generators like Next.js, Gatsby, and Docusaurus.
    • It also rules out solutions that lean into pure Markdown, but these are usually marketed towards use cases like API docs, not blogging.
  • I need good documentation for when things go awry. It doesn't have to be amazing, or even great - just good will suffice. Good documentation doesn't just cover all the features; it explores those features from the perspective of the user, organizing information in terms of things you might want to do, not just mirroring the codebase. Good documentation is also ideally up-to-date with the latest release, since that's the one I'll be using.
    • I tried Hugo for awhile, but its development server had trouble picking up changes to the site, and the documentation didn't offer any pointers. I went to try out theming in Hugo and was slapped with an outdated information disclaimer; that's where my browser history for Hugo ends.
  • It needs to be a stable foundation for years to come. This is hard to gather from a birds-eye view, but from spending years upon years in this space, I've slowly honed a sense of whether a project's perceived inertia is owed to quality or just hype. Even something as basic as the project's name or URL can fail the sniff test, but glancing at their homepage tends to be foolproof.
    • This rules out Next.js (again), Nuxt, and Astro, whose websites all carry the je ne sais quoi of a cryptocurrency funding scheme (whether true or not).

Eleventy's homepage features a banner calling for justice for Asian American victims of hate crimes, plus a balloon-tied opossum floating across the page. The documentation button halfway down the page is comically enormous and sticks to the screen. These are the vibes I want.

Bridging a small ocean

Migrating across frameworks is more than just moving files around to match a new directory structure. It's more than fixing the template variables and writing a new configuration file from scratch. (Don't get me wrong, it's still a lot of that by volume!) It's reconciling your entire mental model of how your site is assembled. The nouns all have slightly different semantics, and the verbs you use to connect them operate totally differently. That wasn't meant to be an analogy to learning a new language, but it fits!

Some things I found difficult to parse from the documentation:

  • Eleventy's directory structure is more flexible than Jekyll's, but it's still semantically meaningful. Just because you can keep your miscellaneous pages in a _pages subdirectory and assign them all top-level permalinks doesn't mean that Eleventy wants you to do that. I don't know how to explain exactly what went wrong here. I think it had to do with pagination?
  • In spite of the Eleventy Supplied Data page, which I want to say is immensely useful, I still have almost no intuition for when to prefix the page-related variable I want with page or data or both. This might be a me problem, but having to write post.date followed by post.data.topics makes me feel like I understand the system less and less every time.
  • You are expected to understand & leverage the Data Cascade. This page is pretty far down the documentation sidebar, and it presents itself as more of a technical reference than a user guide. Nonetheless, the data cascade is how you accomplish some - in my opinion - very basic tasks such as "assign everything in a collection the same template".

Actually, since this begs an answer, here's how I did it:

How to assign everything in an Eleventy collection the same template

  1. Keep all members of the collection colocated within a directory.
    • In my case, this means keeping all my blog posts in the _posts subdirectory. This is a reasonable restriction for me; hopefully it works for you too.
  2. Create a JSON file with the same base name as the enclosing directory, e.g. _posts/_posts.json.
    • You can put frontmatter in here (except translated to JSON fields) and it'll recursively cascade to everything in that directory.
  3. Add {"template": "my_template_alias_or_path"} to the JSON file.
    • That's it! Easy peasy once you know what to do.

Why doesn't the documentation just come out and say this? It's not painfully hard to synthesize, but it took a lot more brainpower than I recall Jekyll ever demanding of me for something so simple. Ugh. It's fine. I'll grant you one less-than-good documentation experience, Eleventy.

Conclusion

Migrating meow.garden from Jekyll to Eleventy took me around 8 to 12 hours, spread over a synthetically long weekend (Saturday, Sunday, and a Monday worknight). The development server isn't perfectly snappy (it takes a few seconds to cold-load a page), but it does come online in under 2 seconds, and it picks up content changes as instantaneously as I need. I'm happy to be on this side of the bridge and excited to continue tinkering with this website!