11ty and Github pages

A bit of history

Around 2018 the first projects emerged using Contentful, GatsbyJs and Netlify. This is still is a great setup for generating static sites.

Jacco Meijer
|
Jan 19, 2022

Contentful, Netlify and Gatsby four years later

What did we learn from using Contentful for four years?

The main drawback? It 's a heavy solution for a simple static site. Mainly because it requires three independent services.

A simpler solution

Besides the GatsbyJs framework, the Contentful setup requires three services to work together:

Contentful
Netlify
Github

Six years later, Netlify grew to be a popular platform for hosting static sites. Github pages also grew in popularity. For this specific setup, switching from Netlify to Github pages eliminates one of the three services.

11ty

If Contentful could be simplified the same way, Github would be the only service required.

Saving the content to Github as Markdown is a simple way to achieve this but brings up a new question. How to work with reusable pieces of content?

Having a closer look at Github pages learns that Github pages is driven by Jekyll and Jekyll uses the Liquid template language created by Shopify for templates.

From Jekyll it is a small step to 11ty because 11ty is the JavaScript alternative to the Ruby based Jekyll.

Replacing Gatsby with 11ty and storing the site content in Markdown allows for removing Contentful from the list of required services.

Migrating existing content

With the new setup, 11ty generates the site HTML which is then pushed to Github. This successfully replaces the Gatsby generated site.

All good! Until existing content is migrated. This brings up two areas of interest:

page metadata and
reusable components.

1. Page metadata

Handling page metadata is a common requirement for Static Site Generators. The Hugo generator handles this by adding metadata to the top of a Markdown page. The metadata is then called 'Front Matter'.

A quick example of Front Matter:

---
date: 2024-01-01T02:16:22-09:00
draft: false
title: Front Matter title
---

11ty uses Front Matter by default and NPM packages exist that handle the extraction from documents.

2. Reusable components

Components in a template world are commonly referred to as 'includes'. Including another piece of Markdown works as a simple component solution.

Markdown renders to HTML and Markdown allows for including HTML. This makes that complex component requirements can be handled with a HTML based solution. Some popular ones are:

WebC, 11ty's answer to Web Components.
Stencil, a popular library for building Web Components.
Native HTML Custom Elements and the new declarative shadow dom, finally gained Mozilla support in February 2024.
JSX, the popular Javascript extension by Facebook/React.

WebC is an excellent solution for reusable components. Especially when using 11ty. But, being familiar with Gatsby and React, how about using JSX functions for components?

NOTE: Zach Leatherman, author of 11ty, wrote a great post on the modern issues of styling these components.

MDX

Combining 11ty, Markdown and WebC is a common approach.

Using 11ty, Markdown and JSX together is not. This is because combining Markdown and JSX is so obvious that it has its own name. It's called MDX and mdxjs.com clearly explains how this works.

While not the most common solution, using JSX as a template language in 11ty is very well possible. Paul Everitt, the PyCharm/WebStorm Developer Advocate at JetBrains, created a JSX setup with Typescript:

https://github.com/pauleveritt/eleventy-tsx

Conclusion

The Contentful-Gatsby-Netlify trio can be simplified by using 11ty and Github pages. Any component solution can be used. For 11ty, WebC components is a solid choice.

Static site generator for MDX

Diving a bit deeper into MDX, it seems that using @mdx-js/esbuild with some custom logic could make Esbuild into a simple but powerful static site generator.

The quest for simplicity continues in the next post!