Building a static site with 11ty

This post describes the process of creating this site using 11ty.

11ty and static site generators

11ty is a static site generator (SSG) based on nodejs. Static site generators take content as markdown or HTML files with metadata at the front of each file, and combine them with HTML templates to generate a website. The generated website is then a simple set of static files, which are easy to host, eg. using a CDN.

I wanted a website where adding content felt similar to editing a wiki, that allowed interleaving markdown and Latex equations easily the way you can in Jupyter notebooks.

Jekyl to 11ty

I briefly had a Jekyl based website. I wanted to essentially host two separate blogs, one professional and one personal, within the same domain. This proved challenging, and required changes to framework Ruby code, a language I have never used before or since.

11ty is less opinionated than Jekyl, and setting up multiple blogs is straightforward. Additionally, since 11ty is implemented in javascrpt, there's less of a barrier between framework and content, and developing it is a more uniform experience.

However Jekyl has much more batteries-included templates. Since 11ty projects are less structured than Jekyl, it is not as easy to separate out reusable templates. 11ty instead provides a list of "starter projects", complete 11ty projects to build on.

I did start with a starter project, but wound up finding it too hard to modify the CSS without creating artifacts like UI elements moving offscreen, and wound up restarting from scratch.

Approaching CSS in 2022

The main reason I originally chose Jekyl is that I hate working with CSS. I only touch CSS every few years, and each time I seem to start fresh, retaining very little of what I learned the last time.

The good news is that the web ecosystem has made progress in recent years, and some things really are easier to do now! The bad news is that searching for very common frontend idioms (eg. sidebar navigation) do not reliably surface tutorials showing easier modern approaches. As a result, I wasted a bunch of time doing layout longhand that wound up being easy using grid layout.

Grid layout is great!

If you're new to web layout, or if you very rarely use CSS, check out docs or a tutorial on grid layout before starting a new web project.

I won't go into detail here, but the idea is that you name each element of the grid (eg. "sidebar" or "content"), then use a CSS grid-template-areas attribute to "draw" what the layout should look like.

This allows you to rearrange the layout between mobile and desktop via a CSS @media query:

@media (min-width: 500px) {
  .wrapper {
    grid-template-columns: 1fr 3fr;
    grid-template-areas:
      "header  header"
      "nav     nav"
      "sidebar content"
      "ad      footer";
  }
}

This way you can present content in a different order, or place regions side-by-side on desktop that are vertical on mobile.

Generally, I find grid layouts to be easily comprehensible compared to an equivalent layout implemented using other methods. Browsers also benefit from understanding that the layout is grid-based, and provide good debugging tools visualizing the layout.

Grid layout has been supported by all major browsers since 2017, so it should be safe for general use in 2022.

11ty extras

I used three plugins to allow light customization of markdown: markdown-it-attrs, markdown-it-bracketed-spans, and markdown-it-div.

This allows you to customize markdown generated HTML a bit without switching to inline HTML. This allows customizing the rendered size of images, for instance, or centering image captions, something that always bugs me in markdown.

Latex support

I work in machine learning, and I wanted to have Latex integration for rendering equations. One of my original motivations for using a SSG was to mimic the combination of markdown + latex that Jupyter notebooks provide.

Getting this to work with Jekyll took a few steps, enough for me to look up Ian Goodfellow's post on how to integrate MathJax.

In 11ty, it's trivial. Simply install the eleventy-plugin-mathjax plugin, and write some equations:

$$-\frac{1}{N}\sum _{i=1}^N\log \left(\frac{e^{Z_{i,y_i}}}{\sum _{j=1}^C{e}^{Z_{i,j}}}\right)$$

Hosting on AWS Amplify

I'd used AWS Amplify Hosting for a previous Jekyll website. Setting it up again for 11ty was trivial.

It connects to most source control hosting providers (eg. Github), and can pull, build and deploy a static site whenever it changes.

The continuous deployment automation is overkill for what I need, but AWS Amplify is worth using simply for the steps it is able to take care of, including:

• Pushing site updates to a CDN (CloudFront)
• Registering free SSL certs for your serving domain
• Ongoing operations, like rotating SSL certs

I even have my own wildcard SSL certs for my domain, but it's honestly easier to have AWS Amplify manage free certs for me and set them up with the CDN.

Links and acknowledgements

The CSS for this site is inspired by the Jekyll minima theme and uses some settings and design ideas from the nonplain-11ty-starter template.

The Itsiest, Bitsiest Eleventy Tutorial is a great, simple tutorial.