Darek Kay's picture Darek Kay

Moving from Hexo to Eleventy

My blog is my digital garden, and I enjoy taking care of it. It's been over five years since my last big redesign. Time for a new look. 🎨

There were also technical reasons for a migration. Hexo had once been a popular choice among static site generators, but now there's not much progress anymore. My pull request fixing a rather annoying bug has been open for almost 3 months, still waiting to be merged. Eleventy (11ty) on the other hand has been getting a lot of attention recently. It's much more flexible than Hexo and in general a pleasure to work with.

Table of contents:

Technical migration

While both Hexo and Eleventy are written in JavaScript, the code reuse was almost zero. This was to be expected, because the underlying model is different. Hexo comes with some blog-specific tooling, while Eleventy gives you a framework to do whatever you want.

First, I've migrated the content. The markdown files mostly remained the same. I only had to rewrite Hexo tags into Eleventy shortcodes. The usage is slightly different, too:

{% alert info %}    // Hexo
{% alert "info" %} // Eleventy

My custom picture shortcode is more complex:

{% picture assets "image" "Alt content" "Optional figcaption" %}

This shortcode finds all available image assets, e.g. image.jpg, image-2x.jpg, image.webp, and creates a responsive, accessible <picture> element. 😲

The next step was to implement all the usual website stuff: favicons, RSS feed, sitemap, microformats, JSON-LD, etc. With Eleventy, it was rather straightforward, even without using any of the available plugins.

Finally, I've recreated some editorial features, like draft management and validation tooling (e.g. making sure a post description is present).

Design

All my previous blog designs were based on existing templates. This is how my blog looked like before the migration:

Previous design screenshot
Previous design

With the new design, it's the first time that I haven't used any third-party theme. I've used some base styles from my other projects and got a lot of inspiration from other blogs. My goal was a good trade-off between minimalism and personality, like the new custom-made cartoon avatar:

New design screenshot
New design

Font

I've always been an advocate for the system font stack, i.e., using native instead of web fonts. But I wanted my blog to have some more personality. I've noticed the Nunito font on some other blog, and I liked it a lot. The drawbacks (performance, flash of unstyled content) became acceptable, when following some web font best practices:

  • Create a font subset to reduce the file size.
  • Preload font files.
  • Use font-display: swap.

Syntax highlighting

Previously, I've been using highlight.js for highlighting code examples. It served me well, but I kept hearing about Prism.js. Prism is also the official highlighter for Eleventy, so I gave it a try.

Pros:

  • Better JSX highlighting support.
  • Many available plugins.

Cons:

  • Worse CSS highlighting support.
  • Insufficient documentation.
  • No way to adjust the wrapping element, leading to accessibility issues. (Update: there is now a workaround within Eleventy)

I have mixed feelings about Prism. After some work it's now usable, but I might switch back to highlight.js in the future.

Performance

I've got to a ~95% Lighthouse score out-of-the-box by following common best practices. After going the extra mile, I've reached the last 5%:

Full Lighthouse score on performance, accessibility, best practices and SEO
Google Lighthouse results

The new website is also fairly sustainable:

Hurrah! This web page is cleaner than 93% of web pages tested
websitecarbon.com results

Accessibility

As an accessibility advocate, I attach great importance to inclusive design.

Again, following best practices is a great starting point. Still, humans make errors, so I'm using evaluatory, a tool I have written, to make sure there are no obvious issues:

"scripts": {
"a11y": "evaluatory --sitemap http://localhost:8080/sitemap.xml"
},
npm install --save evaluatory
npm run a11y

I also took the time to finally implement anchor links in a more accessible way.

Bonus

Inspired by Will Boyd's easter egg, I've added a hidden feature on my blog as well. 🕵️‍♂️

Conclusion

It has been a fun journey. Eleventy is a great, flexible static site generator that I enjoy working with. The final design is clean and simple. I've also learned a lot and got some new post ideas along the way.

Stay tuned 🔥


Related posts

Want to leave a comment?

Join the discussion at Twitter, Mastodon or Dev.to. Feel free to drop me an email. 💌

Moving from Hexo to Eleventy