Skep's Place

Friday Morning

AKA "a lesson in how not to do documentation"

I am following Evelenty's official Get Started guide (as of May 2025). To show you exactly what kinds of problems I'm having and why this is so needlessly difficult, I'm going to walk through the intial steps and point out every way in which this guide fails for less-savvy users like me.

(Am I mostly doing this for the catharsis? Absolutely yes.)

First, the guide states that Eleventy requires Node.js. This is the kind of thing that falls into the category of "things I've heard of but couldn't tell you what they do". Fortunately, I don't think we're going to be required to learn Node.js today, we just need it to run a couple commands via command line. Go ahead and install it.

My favorite part of this preamble is that Eleventy helpfully provides a link to a documentation article labelled Well, wait—what is a Terminal? This is a very kind offering to somebody who maybe doesn't yet have a full understanding of what is going to be required by this utility. This is also the last time we're going to get anything like this, so good luck if this is you.

There's also a link to a video claiming "learn this in 6 minutes". Buddy, I'm dedicating an entire weekend to this. I don't want a 6-minute video, I want a 6-hour video. I actually want to learn this shit rather than watch somebody cram a setup process into a TikTok.

Okay, let's actually get to Step 1 (you can click to open all these images by the way):

So what we're doing here is making a folder to hold all of our new stuff, and then navigating the command line to that folder so that the future commands will run inside it. You can create the folder in your file explorer if you want. The only reason to do it their way is because navigating to folders in the terminal is tricky. The downside is it's probably going to create the folder in your user folder or something, which might not be where you want it. I don't love this, but it's fine. Let's move on.

npm is invoking the Node.js package manager, which is basically what's going to run Eleventy I guess. Like the guide says, the first command here creates a package.json file. What is this? No clue. I assume it's important. Just roll with it for now. Then the guide says "Use the following command if you want to use ESM in your project and not CommonJS."

Problem 1: Do I want to use ESM in my project rather than CommonJS? There is a link to a page that kinda describes the difference between the two in a way that I'm sure makes sense to somebody. There is a line buried in there which more or less says ESM is a newer standard that works in more places, and my research seems to confirm this, so I guess we should go with that.

Problem 2: If I do want to use ESM, is the guide telling me to use the specified command in addition to the first one, or in place of? The answer is "in addition to", but I only know that because I tried it. Now you don't have to. It adds a line to the package.json file which, again, I'm sure indicates something very important.

Great, now let's actually install Eleventy.

This will do two things:

1. Creates package-lock.json. Again, have to assume if it wasn't doing anything useful it wouldn't be here.
2. Creates the node_modules folder. This is the application, so don't touch it. But on the plus side, look, a thing I can actually identify (I hope)!

Time for Step 3:

This step is entirely, 100% without-a-doubt skippable. We're running Eleventy. Except we didn't give it any files so there's nothing for it to do. That's what the output at the bottom is saying. "I didn't do anything." We dedicated an entire step to this. Terrific. Let's continue.

If you're not used to the command line, this looks confusing. It's actually really not; all it's doing is creating two files and populating them with content:

• index.html, which only has a page title and a paragraph tag that says Hi.
• README.md; this is a Markdown document (in basic terms, Markdown is just a way to format text that's simpler than HTML) that only contains a heading that says Heading.

Thing is, you can just as easily create these files by hand, and it would be less confusing if you're not familiar with the command line. Because then you'd actually be making them yourself, rather than running a command and maybe eventually realizing "oh look, these files appeared at some point".

Step 4, continued:

We're using npx to run Eleventy again, and this time something is actually going to happen now that we have files. The project now contains a new folder called _site which has the following:

• index.html, the original HTML file.
• A folder called README which contains another file called index.html. Eleventy has converted the Markdown file to HTML.

But what caught me off-guard at this point was that README was a separate folder, rather than a file named README.html. I expected that since I had two files in the same folder, it would export two files in the same folder. Nope. I had to look this up, but apparently the reason for this is that "www.site.com/README looks nicer in the URL bar than www.site.com/README.html". Which is true, but when I go to generate my Three Kingdoms chapter summaries, I tell you right now I absolutely don't want this thing to generate 120 different folders each containing a single index.html file. Insane that this is the default. So I'll have to figure out how to turn that off at some point.

Something else I didn't want to gloss over: if you look at the command output, each line shows what file is being written, and then in parentheses says (liquid). Liquid is... a thing that the guide references but doesn't explain, so I can't either. Moving on.

One last step:

What this is doing is starting up a fake web server so you can preview the site. As long as this server is running, you can access the site in your browser by navigating to http://localhost:8080/.

They make it sound like the benefit of doing this is that you can edit your files and view the changes relatively "live" rather than rebuilding the site each time. This sounds useful, but if you powered through the command line and don't know where your files live, kinda tough shit because you now need to edit them in a text editor. You might remember that the guide didn't ask you to create the files this way, but now you're editing them this way. Just one of those nice little touches nobody seemed to consider.

The other problem is that these files don't include any natural way to navigate between them. You'll need to edit the URL directly to view the README file.

Great, now we're done! Did you learn anything?

...No?

Yeah, me either. I guess I can run this thing now. But after an entire morning at this, I still don't know how it works.

Time for more tea.