DEV Community

loading...

Moving from Hexo to Eleventy

darek_kay profile image Darek Kay Originally published at darekkay.com ・4 min read

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.

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
Enter fullscreen mode Exit fullscreen mode

My custom picture shortcode is more complex:

{% picture assets "image" "Alt content" "Optional figcaption" %}
Enter fullscreen mode Exit fullscreen mode

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

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

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.

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

The new website is also fairly sustainable:

Hurrah! This web page is cleaner than 93% of web pages tested

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"
},
Enter fullscreen mode Exit fullscreen mode
npm install --save evaluatory
npm run a11y
Enter fullscreen mode Exit fullscreen mode

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 🔥

Discussion (0)

pic
Editor guide