Yesterday, as planned, I followed fLaMEd’s guide to getting started with Eleventy. In only an hour or two, I had a really basic site: a landing page, an About and Contact page, and a Blog page that listed individual blog posts. Rad!
Keen observers will also notice there is some basic CSS styling in this screenshot. I know! I said no CSS! In my defense, I copied the CSS that fLaMEd provided, and have not touched it one bit since then. I am not tinkering with CSS. I am not making things pretty. I am trying to understand the system.
Speaking of, how am I doing on that front?
What I do and don’t understand #
I wrote in my last post about my inattention and my history with my website, and I briefly mentioned my basic familiarity with HTML and web design, but I didn’t really give a good glimpse into where I’m starting from.
I’ve been tinkering with web design since elementary school. I’m familiar with HTML and CSS, although my CSS-ing usually involves a lot of trips to reference documents to remind myself of the exact details of how something works. I am slow and inefficient, but can usually get there.
My weakest link, when it comes to understanding Eleventy, is JavaScript. At this point in my life, I have probably taken (or started) at least 10 introductory programming tutorials, between JavaScript, Python, Lua and PHP, so again, I’m not unfamiliar. I understand all your Programming 101 concepts: variables and data types, flow control, functions. What I lack is proficiency. Even more so than CSS, it takes me a lot of concerted effort to read a program and understand what it does.
So, with that background, here’s where I am today in my understanding of Eleventy.
I understand the basic concept of a static site generator: the user provides a directory of input, and a program (Eleventy, in this case) processes it and spits out a website in an output directory. I understand how to use layouts and Nunjuck templates to shape how individual pages look, and I get using partials for reusable code. So far, so good; this is conceptually not that far off from how Hugo works.
After finishing the tutorial, though, and beginning to tinker, I had a lot more questions start to emerge, like:
- Wait, just where is any given Nunjuck template pulling its data from? How do I correctly target the data I want?
- Can I write reusable code (a partial, a shortcode) that takes one or more input variables? Say, “list all the posts in [given collection], and preface their titles with [given emoji]”.
- Can I make categories, or other post taxonomies, in addition to Eleventy’s built-in tags?
- How can I build a collection that consists of multiple subsets (say, all watches, reads, and links)?
- What’s the functional difference between a partial and a shortcode? When would I use one or the other?
- Can I bundle resources for a given page in a subdirectory, similar to Hugo’s page bundles? (I hope so, because that’s how my content is currently organized!)
- How do I fetch and use data from a web API? For instance, can I programmatically fetch metadata for a book when I make a new Read post about it?
I’m also finding myself running into my unfamiliarity with organization for a large programmatic project like this. “Wait, should I be making that a partial so I can reuse it?” I don’t know how much flexibility to bake in at this stage. Maybe I shouldn’t worry about that. I can always go back and add flexibility later.
What I’m seeing is that there are two large gaps for me. The first is the aforementioned missing proficiency with JavaScript. The second, and probably the more critical one, is a more acute understanding of how this whole Eleventy engine works. Yes, I know the bird’s-eye view—Markdown and templates go in, HTML comes out—but I want the next step of acuity.
The temptation to “cheat” #
As I do all of this, I am keenly aware that Brennan, bless him, has already made an Indieweb starter project for 11ty. I could, at any point, jump ship from this rocky learning experience, download that, and start customizing it. And at times, it’s tempting.
But I’m reminding myself that this would put me right back where I was with Hugo and Blowfish. Even though the starter project was made by an experienced designer, and even though it has all the hard work done, it’s not mine. I’m doing this as much for the learning journey as the ownership I’ll have over the outcome.
And besides, I really don’t like how much that starter project relies on Tailwind. Mostly because I don’t know Tailwind, but also, I’m stubborn and weirdly opinionated and don’t like the layer of obscurity that frameworks like Tailwind introduce, with all their functional classes. class="container mx-auto px-4 py-2 hidden md:block just isn’t how I want to write my site, for better or worse.
Learning good practices and becoming opinionated #
Speaking of opinions, I had already made some opinionated decisions, which I failed to mention in my previous post:
- Use minimal (if any) client-side JavaScript: Nathaniel’s “Why your website should work without Javascript” is a nice encapsulation of my reasoning here. I care about the accessibility, speed, security, and ease of development of not using front-end JavaScript.
- Build with minimal size in mind: Now, this is not going to be an austere, TTY-inspired site. There will likely be images, because I like pretty things. But I want to be mindful of my resource usage, and aim for smaller and simpler when I can.
- Use semantic HTML and selectors: I find semantic markup and styling solutions like SimpleCSS incredibly elegant, so I want to build the site skeleton with that in mind.
Additionally, I’m now building with these opinionated decisions:
- Cool URIs don’t change: I have not been good about this in my history of managing my web presence. Oops. But this seems like a perfect opportunity to institute an intentional permalink policy. I’m thinking larger articles will have permalinks at
yyyy/mm/title-slug/, and smaller notes will live by default atyyyy/mm/hash, with some variance for specific post types. I’m not sold, though. I’m overthinking this one, trying to find the perfect URL scheme. 🙄 - Accessibility!: I knew accessibility was important, of course, but I didn’t quite know where to start. Luckily, the World Wide Web Consortium has an accessibility guide, and the Mozilla Developer Network has one too. It’s a lot to digest, but this will help me plan for accessibility from early on.
Today’s work #
It is tempting to keep hacking at the current skeleton, but in the interest of building proficiency, I’m going to follow another tutorial. Today it’s going to be the Learn Eleventy course. I found myself browsing through it yesterday anyway, and it seems a bit more developed than fLaMEd’s quick start, so it should give me more practice with some of the areas I’m uncertain about.
And that’s probably enough time writing: once again, back to work.