Skep's Place

Friday Evening

Jesus christ, I'm on step two of this project and I already need to implement a goddamn workaround.

You remember this morning, when I ran the build after adding the two starter files per the guide, and I noticed that README.md became a folder called README which contained an index.html file? And I said I was going to have to figure out how to turn that off because I didn't want my Three Kindgoms summary to create 120 individual folders each containing a single file?

Well it turns out the developers never implemented a switch to turn this off because they are SO CONVINCED this is the proper behavior:

Long story short, they're saying that perhaps 20 years down the road Skep's Place will no longer be built on HTML but something with a completely different file extension, and if I do it their way then all of the existing links to my site will still work. This is technically a valid argument in the same way that "I should be putting an additional 20% of my salary into my 401(k) because there's a chance I might live to the age of 150" is also a valid argument.

I'm starting to regret choosing Eleventy, but if I give up now there's a good chance I'm just going to hand-edit HTML files until I die at age 150. So let's keep rolling.

Saturday update: To make all this even more ludicrous, I just learned that my host Neocities does automatic URL cleaning anyway.

THANKFULLY I found a solution on Eleventy's GitHub page shared by user flameddd, found here. Seems pretty elegant. If you're reading this, I owe you a drink.

First, though, we need to add a new file to our folder: eleventy.config.js. This is the file that will contain the settings we want to use for Eleventy. Unfortunately, this won't be as easy as "setting = value". Feels like it could be, but I guess this is why I'm not a developer.

Once that's created, you can paste in flameddd's code:

export default function(eleventyConfig) {
  eleventyConfig.addGlobalData("permalink", () => {
    return (data) => `${data.page.filePathStem}.${data.page.outputFileExtension}`;
  });
}

(You will notice this isn't exactly flameddd's code. Remember when we had to make that choice between CommonJS and ESM? Yeah, this was probably done before ESM was even a thing in Eleventy, so it was written in CommonJS. Didn't work the first time I ran it. Thanks to the documentation I was able to correct it for our use.)

I'm not fluent enough to fully say how this code works, but essentially what it's doing is telling Eleventy to output files with the original path/file name plus the new extension. Now we're cooking. I played around with this, and whatever file structure you start with, that's what it seems to give you after you run the build. Fantastic. That took way too much effort.

The other thing I wanted to do at this point was set an input folder. Our .html and .md files were just sitting in the project folder next to our package.json and config files and all that. I for one don't like that, because I'm just going to get them mixed up with the site files I want to use as my input. It's messy. And while I'm at it, let's change the name of the output folder. Not that _site is bad, but we can do better. So, based on the documentation, I added this to eleventy.config.js:

export const config = {
  dir: {
    input: "_input",
    output: "_output"
  }
};

All it's doing is defining what we want our input and output folders to be. Now when we run npx @11ty/eleventy, it's going to read the files we put into our new folder named _input, and spit the results into a new folder named _output.

God, how simple.

Anyway, that's enough of this headache for tonight. Tomorrow, I think it's about time to figure out how to break my site apart and make templates out of it.