Marcin Morawski

Moving this website to 11ty

Why #

This blog is built using a static site generator. I originally used Hugo, but their templating engine is notoriously difficult to use, and documentation is often lacking. This meant that instead of learning how it actually works, I ended up copying and pasting random bits of code to create my layouts. I decided that it would be good to rewrite the site in something that would be easier to learn, which would incentivise deeper understanding.

After a brief research phase, I decided to use 11ty. It's supposed to be focused on simplicity and ease of use, and more integrated into the frontend development ecosystem.

How #

Learning #

I started by going through this really good tutorial from 2020. It's a bit out of date, but it's very well-written, and assumes little previous knowledge. It explains the inner workings of Nunjucks (one of 11ty's templating languages), and key concepts such as collections.

Implementation #

Then, I cloned the eleventy blog starter repository and made some light modifications to make it just like my previous website.

Modification list:

Deploy #

I then deployed the page on GitLab Pages. The CI template provided by GitLab did not work - it required all the build artifacts to be in a public folder, which for some reason did not work with my build. The following CI config worked for me:

default: 
  image: node:lts

stages:
  - test
  - pages

test:
  script:
    - npm install
    - npx @11ty/eleventy
  rules:
    - if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH

pages:
  script:
    - npm install
    - npx @11ty/eleventy
  artifacts:
    paths:
      - _site
  publish: _site
  
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

Opinions #

The migration was a bit of a pain, mostly because a lot of my image and video processing functions were implemented as Hugo shortcodes. The 11ty version uses pure markdown for everything, which should hopefully be more portable if I ever decide to change again. So far, I am very pleased with 11ty. Everything just works. There are well-documented plugins for almost everything that I want to do, and for the things that there aren't off-the-shelf plugins for, I have the entire node.js package registry at my disposal. Scripting things directly in javascript is great for quickly hacking things together.