Simple Does It

Is it just me, or has tech just gotten too damn complicated?

Every week there is a new tool, with a new set of dependencies and configurations, to be installed on a new stack: too much to learn that is too seldom used and too frequently forgotten.

My needs are simple. I just want to write content in a simple text editor using Markdown, and then publish that content to a simple, easy to maintain web site that uses vanilla HTML, CSS, a little Javascript maybe (but only if absolutely necessary), no packages, no dependencies, light to load, easy to update. Simple.

I began my quest as one does: by being sucked down the Google worm-hole of blog posts and tutorials. Every "quick-start" I tried installed a dizzying number of dependencies and mountains of boilerplate which usually worked, but seldom made sense, and always required more new things to learn.

Until, that is, I found the perfect combination: GitHub Pages and Eleventy.

It all began when I got a simple website working by following the GitHub Pages Quick-Start. Unfortunately, however, the next stop on the GitHub Pages journey required that I learn Jekyll, which looked suspiciously like the very complexity I was trying to avoid. Seriously, have you seen how much shit Jekyll brings with it when you install it on your computer?

Back on Google, and scanning the SSG (Static Site Generator) horizon for other options, I spied a promising alternative to Jekyll: Eleventy.

Within a few minutes, I got a simple Eleventy site working by following the Eleventy Quick-Start. One of the things I most love about Eleventy is that you don't even have to install it as a dependency in your project! As long as you have npm and node installed, you can simply use npx from the command line to generate your site content.

Sadly, Eleventy doesn't work 'out-of-the-box' with GitHub Pages. And because of that, for a little while, I was briefly sucked back down the Google rabbit-hole of posts and tutorials with extra steps, packages, and configurations (custom GitHub Actions or package.json files defining node package dependencies to assist with the build). I just want a static site! No extra shit!

Finally, after much searching and swearing, I stumbled on this simple blog post by Lea Tortay which showed me the way: a minor change to the default Eleventy folder structure that allows you to push to GitHub and deploy the Eleventy-generated static site to GitHub Pages automatically - no additional packages, no GitHub Actions, no cruft.

Change default GitHub Pages configuration at Settings > Pages to deploy to /docs folder instead of /(root).
Go to your local project
```
$ cd /path/to/local/project
```
Add a .nojekyll file to the project root (this tells GitHub Pages to skip the Jekyll build):
```
$ touch .nojekyll
```
Add a config file for Eleventy

Surprisingly, even this was a little tricky. There is a lot of Eleventy documentation, but I personally don't find it very easy to find the things you need out there. It took me much longer than I would have liked just to figure out where the base eleventy.js config file goes (spoiler alert: it goes in the project root):
```
$ vi eleventy.js
```
Add the following:
```
module.exports = function(eleventyConfig) {
  return {
    dir: {
      input: "src",
      output: "docs"
    }
  }
};
```
This tells eleventy to look in src for files to build, and to output static files to docs.

Change default Eleventy structure accordingly:

$ rm -rf _sites
$ mkdir src
$ mv _includes src
$ mv index.md src

Rebuild static files with eleventy command (this will now automatically create the docs folder and put all statically generated content in there):
```
$ npx @11ty/eleventy
```
Push to GitHub

And Bob's your uncle. That was easy!

So far, I must say that I'm quite impressed with the combination of GitHub Pages and Eleventy. For me, these are two great tools that go great together.