Presently my favorite Static Site Generator (SSG) is 11ty. I love 11ty for many reasons first its adaptability, customizability, speed, and stability. 11ty unlike WordPress and Jekyll gets out of the way and allows me to focus on content. Jekyll feels fun but as many have said it feels abandoned/stalled. Perhaps due to Jekyll being stalled, Dependabot is consistently giving me notices and alerts, which I appreciate but it takes my time away from other things. Likewise I'm consistently fussing with settings on Github Pages and Netlify to get Netlify to deploy. None of those issues exist when I am working with 11ty. Therefore one of my goals for 2025 is to transition away from Jekyll and towards 11ty.

One of the things that is overwhelming to me about 11ty is just how customizable and open it is. I frequently find myself overwhelmed by the fact that everything is possible but I am limited by my own skills and ability (which fair). Another barrier that trips me up is often 11ty feels and acts so similar to Jekyll that I get surprised and confused when 11ty doesn't work like Jekyll.

Over the holiday break I decided to work with Creativitas.dev&emdash;a colleague from the 11ty community&emdash; on adapting/porting a Ed. a #minicomp theme for public humanities.

Process #

What I started by doing was taking the Jekyll theme, breaking it down into its component parts and then 11ty-ifying [sic] them.

Directory Structure #

I roughed out the following directory structure 11ty-eddy

├── LICENSE.md
├── README.md
├── _data
│   ├── metadata.json
├── _includes
│   ├── article.njk
│   ├── base.njk
│   ├── home.njk
│   ├── narrative.njk
│   ├── partials
│   │   ├── aside _narrative.njk
│   │   ├── aside.njk
│   │   ├── editor_notes.njk
│   │   ├── head.njk
│   │   ├── header.njk
│   │   ├── menu.njk
│   │   ├── menu_narrative.njk
│   │   ├── narrative_info.njk
│   │   ├── nav.njk
│   │   ├── search.njk
│   │   ├── sidebar.njk
│   │   ├── sidebar_narrative.njk
│   │   └── toc.njk
│   └── textslist.njk
├── content
│   ├── index.md
│   ├── pages
│   │   ├── 404.md
│   │   ├── about.md
│   │   ├── credits.md
│   │   ├── documentation.md
│   │   ├── pages.11tydata.js
│   │   └── search.md
│   ├── sitemap.xml.njk
│   ├── tag-pages.njk
│   ├── tags.njk
│   ├── texts
│   │   ├── drama
│   │   │   └── raisin.md
│   │   ├── narrative
│   │   │   └── narrative.md
│   │   ├── poem
│   │   │   ├── a-julia.md
│   │   │   ├── delayed.md
│   │   │   ├── dreams.md
│   │   │   └── o-captain.md
│   │   └── texts.11tydata.js
│   └── texts.njk
├── public
│   ├── css
│   │   ├── main.css
│   │   └── nu.css
│   ├── img
│   ├── js
│   │   └── main.js
└── END

The biggest changes that I made were first splitting the texts out by type to make it easier for me to template in 11ty and to see visually in my codebase which texts are using which layout types. Next I had to wrap my head around Jekyll layouts and includes versus 11ty includes and partials. As I was porting the template, there were so many differences that in order to better focus and make problem solving simple, Creativitas recommended splitting the partials up into very small files and that helped tremendously with the issues.

SCSS --> CSS #

Another big change was moving away from SCSS to CSS because I want to be able to use and teach this template in a public humanities course and while I love SCSS I think for students CSS might be easier? We will see.

Liquid #

Thanks to Creativitas assistance and thanks to this tutorial by Thomas Broyer, I learned that when adapting Jekyll to 11ty there are differences in liquid templating and while minor they are still important. Katie Kodes outlined the 5 things you need to know about Jekyll vs. 11ty Liquid includes.

Markdown #

The next big issue with adapting this template was markdown processors. I am most familiar with Kramdown but 11ty defaults to Markdown-it so then we had issues with footnotes and table of contents two vital features of this theme. Thankfully robb knight and Bob Monsour over on Mastodon were able to point me in the right direction. Also Bob humorously reminded me of the awesome resource that is his site 11tybundle.dev.

Markdown Plugins #

Thanks to these fine folks, 11ty TOC, and markdown-it-footnote the template now has a Table of Contents and Footnotes! Both plugins were very straight forward to add. Also shout out to the community repository plug11ty.

pagefind #

the next change that we made to the template was replacing lunr JS with pagefind. I really love pagefind it is such an excellent and lightweight search bundle but it constantly give me fits setting it up in 11ty. Someone should write a post on how to add page find easily to 11ty.

Other changes #

• We also updated to the newer Hypothes.is bookmarklet
• We also added language: to texts front matter so that browsers can be notified if sites have multilingual content.

Conclusion #

Overall it took fifteen hours for Ed to become Eddy. Porting this site would not have been possible without the wonderful folks in the 11ty community and the brave folks who not only #BuildinPublic but also blog and talk about their experience so that others can learn from them. Once again building anything is an activity that is best done in community, at least for me.

Tags : website 11ty