What’s the absolute simplest approach to put words on a web site in 2022? As with all things under the sun: it depends! But if you’re the type of person who would like to set up a git repo and run an npm install — the most enjoyable approach might be to do that with static site generator Eleventy.

Eleventy quickly builds speedy web sites. Originally pitched as the JavaScript alternative to Jekyll, Eleventy has matured into a popular modern web site generator.

Static site generator 🎈

No CMS, no database. The shortest config I have seen all year. Yup, this blog can happily soar into the sky with nothing but static HTML and CSS. We don’t even need to push any JavaScript to the browser to handle syntax highlighting — our code examples will get colours from a plugin at build-time. Eleventy supports multiple templating languages, I went with Mozilla’s Nunjucks to power up the HTML.

As little CSS as we can get away with

Browsers are packed with built-in styles. Visually kinda plain, but super useful if we manage to not reset them or break their awesome functionality. If you are a developer who is used to spinning up toolkits for layout, you’d be forgiven for not knowing how snazzy browser styles actually are. The web is fluid and content is responsive out of the box. Mobile or desktop or whatever, I don’t need media queries or other CSS for the layout here to adapt to different viewport widths.

One important improvement to readability on large screens; I want to define a maximum width to prevent lines from becoming ridiculously long. Typography geeks also call this measure but it means the same as line length. I will aim for a maximum of 90 characters, slightly higher than the number sometimes recommended, but for this type of text I think it works nicely. Because the line height is generous and the paragraphs have space to breathe on each side.

/* Wrap content with one tiny reusable rule */
.responsiveContentWrapper {
  max-width: 48rem; /* Line length at max 90 characters */
  margin: 0 auto; /* Center if wide viewport */
  padding: 0 1rem; /* Padding for narrow screens */
}

CSS Stats reports a file size of 2KB and only 30 selectors with the current styles. 🥰 EDIT: ops that was before syntax highlighting, now it’s… 3KB and 72 selectors which is still pretty neat.

Write posts in Markdown

These words are written in a hello-world.md file, inside the posts/2022 directory of the project repo. The result is a post on a URL ending with /2022/hello-world/. Writers can create their posts in their favourite code editor, or directly in the UI on github dot com for those who prefer that workflow.

Headings, code blocks, lists, tables, line breaks, tables and other formatting with markup language directly inside the text file. Cue link to markdownguide.org/basic-syntax 🔖

Dependencies to count on one hand

These are currently the only dependencies in the package.json. The site generator itself, one plugin and our internal tooling for linting and formatting. That’s it!

  "devDependencies": {
    "@11ty/eleventy": "1.0.2",
    "@11ty/eleventy-plugin-syntaxhighlight": "4.2.0",
    "@amedia/kragl": "1.2.2"
  }

If this blog project becomes a roaring success where many people are typing a whole lot to produce posts, we’ll probably want more dependencies. But this is a lovely way to start without complexity.

GitHub Actions --> GitHub Pages

I can now use GitHub Pages: Custom GitHub Actions Workflows (beta) to deploy directly from the repo using GitHub Actions. Until recently, this had to be done with a publishing source typically set to a specific gh-pages branch and using a third-party Action from Marketplace. Now I could write a .github/workflows/deploy.yaml only using standard Actions from GitHub. A previous quirk is that you also needed an empty .nojekyll file to instruct GitHub Pages that the project was not using Jekyll.

The repo needs this setting: Pages > Settings > Build and deployment > Source: GitHub Action

An Eleventy gotcha is that npm run build command needs a --pathprefix with the repo name:

"build": "rm -rf ./_site && npx @11ty/eleventy --pathprefix=jotter"

If we change the blog URL, this is where to change the paths for the build inside _site, so that the HTML there also has correct paths to CSS and relative URLs to posts. But for now, hello world amedia.github.io/jotter 😎