Colophon

Assumed Audience: Folks curious about this site's design and tooling; probably mostly Future Me

Last updated:

Introduction

I’ve documented some of the ideas, features, and design decisions of ATOMWOLF.

This probably isn’t really a colophon, anymore, but it started as one! Any time I read the word "colophon", I start building a joke about a Raffi song.

Goals

I want this site to be full of pages that sound like me.

I want it to be fast and privacy-friendly.

I’d like this website to be usable by the widest possible audience, regardless of tools or even ability. I want it to work on a variety of screen sizes. I want it to be easy to use whether you’re on a desktop or phone or if you’re using a screen reader or if you’re in a weird browser or in a feed reader or if you printed it out. I want it to work well regardless of your processor or network, whether you’re colorblind or have a hard time with things moving when you’re trying to read or are just tired. (This shouldn’t be considered an exhaustive list.)

I want this site to be pretty, folks.

I don’t want to be inflammatory or controversial for clicks.

Accessibility

Accessibility is important to me. If you run into an issue, please let me know.

Tools

I use Eleventy, a static site generator, to generate the site. I started from the Eleventy Base Blog.

I have a variety of little scripts and tools that run over the built files before they’re deployed. These include vnu, pa11y, hyperlink, Playwright, and Lighthouse. I can run these using npm run but I also run them using GitHub Actions.

Hosting

I currently host the site using a bevy of Amazon services. Cloudfront serves the site, S3 stores the files, Route 53 handles DNS, and Certificate Manager handles SSL certificates. It’s low-cost, fast, pretty reliable, and provides request logs. I don’t recommend it for others. It took a bunch of work to set up, and I’m constantly worried that I have misconfigured something or they’ll change something and I won’t notice.

In early 2024, I hosted the site using Cloudflare Pages. Cloudflare Pages is much simpler to use, fast, free for almost everyone, but didn’t provide request logs. Cloudflare wanted you to have an enterprise account (with “contact us” for pricing). For a while, I used Cloudflare Workers to create my own logs, but it added somewhere between 30 and 80 ms of latency. In 2022, Cloudflare announced that “over the coming months”, they would provide logs to all customers regardless of plan. I hope those months come soon! If request logs aren’t necessary, or if 30-80 ms of latency is OK, I recommend Cloudflare Pages. It’s much simpler to configure, has great defaults, and is free for almost everyone.

JavaScript

I aim to create a site that works fine without needing JavaScript in the browser.

JavaScript is used to

Sidenotes

I’m using Tufte CSS-style sidenotes. Tufte CSS distinguishes between "sidenotes" and "margin notes", with margin notes being unnumbered. I'm not sure that I know what my opinion is yet. I’ve made some changes—for instance, sidenotes are shown by default even with narrower viewports.

When copying a paragraph, the sidenotes are copied inline where they were referenced. I think I like this.

Layout

In retrospect, it seems like much of the design is driven by a few ideas.

First, I want a decent design for screens ranging from small phones to large desktops.

Second,

Third,

How are columns positioned and sized across screen sizes? What about on pages without a Table of Contents? What about on pages without sidenotes?

When there isn’t a Table of Contents but there are sidenotes, on medium screens, I think I want a two column layout, with the body column wider than the sidenotes column, and roughly equal left and right page margins. This creates a body column that isn’t centered on the page.

For a long time, I planned on having the three column layout be asymmetrical–the table of contents on the left would be smaller than the sidenotes on the right, and the main column wouldn’t be centered on the page. I had it this way for months, struggling with it. Should the header be aligned to the page, or to the main column? What about the footer? I may end up going back to this, but for now, I’m trying out symmetry to bypass those questions.

On small screens, I want a single column. On large screens with all three elements, I want three columns.

Headers

I try to use only two levels of headers under a title.

Hovering or clicking on most headers reveals a silcrow (§) to the left. The silcrow links directly to that header.

There’s a CSS transition that highlights the silcrow when you hover over or tap the header. It lingers for a while, so the icon doesn’t disappear as you move your cursor to click it.

Block Quotes

Block quotes are indented and have a nice chonky left border.

Ah, Perry the Platypus, your timing is impeccable—and by impeccable, I mean completely PECCABLE!

— Dr. Heinz Doofenshmirtz

Gromit, that’s it! Cheese! We’ll go somewhere where there’s cheese!

— Wallace, Wallace and Gromit

You can even have multiple paragraphs in a block quote.

Erdős knows about more problems than anybody else, and he not only knows about various problems and conjectures, but he also knows the tastes of various mathematicians. So if I get a letter from him giving me three of his conjectures and two of his problems, then it’s sure that these are exactly the kind of conjectures and problems I’m interested in, and these are exactly the kind of questions I may be able to answer.

Of course, this applies not only to me, but to everybody else. So Erdős has an amazing ability to match problems with people. Which is why so many mathematicians benefit from his presence. Every letter is likely to inspire you to do some work, or every phone call will give you some problems you are interested in.

— Béla Bollobás, of Trinity College, University of Cambridge in N Is a Number: A Portrait of Paul Erdős (1993)

Borrowing from Tufte CSS again, there’s styling for epigraphs, for opening a section with a block quote or a series of block quotes from literature.

I love how The Locked Tomb series rewards thinking and rereading without being boring or stodgy. I'm so excited for Alecto the Ninth!

In the myriadic year of our Lord—the ten thousandth year of the King Undying, the kindly Prince of Death!—Gideon Nav packed her sword, her shoes, and her dirty magazines, and she escaped from the House of the Ninth.

— Tamsyn Muir, Gideon the Ninth

“Certainly not. Like everything else in this ridiculous conglomeration of cooling gas, it’s perfectly explicable, I just need to explic-it.”

— Palamedes Sextus, Gideon the Ninth

Right now, my generator doesn’t handle the <cite> tag and cite <blockquote> attribute. Harrumph.

My older homemade markdown-it block quote plugin handled nested block quotes better than the one I’m using now, markdown-it-attribution, but my old plugin doesn’t generate the markup I like these days.

Code

Code blocks are highlighted at build time using Shiki. The code is already syntax highlighted when it’s downloaded, and the highlighting doesn’t require the browser to load and run JavaScript.

The code blocks were originally formatted with Prism, which was built into the Eleventy starter. It did all the syntax highlighting at build time, like I wanted. It was tricky, though, to get line numbers to work. I’m not sure what the problem was, but there were pages and pages of folks struggling to get line numbers. I found a few blog posts at Snapstromegon that showed how to add Shiki to Eleventy to do the syntax highlighting, and it had line numbers built in.

The line numbers don’t copy when you copy the code block. Nifty!

def main():
    print("Hello, world!")

Long code blocks scroll horizontally.

def main():
    print("This is the line that never ends! Yes, it goes on and on, my friends! Some people started typing it not knowing what it was, and they'll continue typing it forever just because--")

I’d really like to be able to do callouts and sidenotes for lines of code. Callouts seem tricky! Ideally, you'd have a readable page and markup that's both readable and still syntactically valid in the source language. I've seen some options that seem fine, but I haven't used any enough to know. Asciidoc callouts, for example, seem fine. Asciidoc can even number callouts if you use . as the handle. I wonder if CSS Anchor positioning would make that nicer?

I think I’d like to have a Copy to Clipboard button.

Table of Contents

Some of the longer pages have a table of contents. In wider viewports, the table of contents is a floating sidebar. In narrower viewports, the table of contents appears inline at the top of the page.

I’d like to be able to skip particular headers in the Table of Contents, but it currently isn’t supported.

Back to Top

Some of the longer pages have a “Back to Top” button. It floats in the lower left gutter, ideally aligned with the section header link silcrows. When you click it, the page scrolls to the top of the <main> element. There’s a little CSS transition to highlight the element when you hover over it.

Having the Back to Top button makes me less interested in having a pop-out table of contents on smaller viewports.

Content Types

At this point, content is split between posts and projects. Posts can be associated with projects, letting me offer project-specific RSS feeds.

I want to use this site to experiment with moving away from lists of chronological content, and provide more of a “digital garden”. I’m not sure how that’s going to happen, but I’m excited to find out.

I’d love to experiment with autopopulating a changelog for articles through commit messages in source control. Not only could this generate a changelog in the document itself, it could generate more traditional “post”-style entries.

Tips/TILs

I’m really inspired by the TIL (Today I Learned) format. I ran into them through Simon Willison, who was inspired by jbranchaud. Share something you’ve learned or explained recently, and do it concisely and be OK without much nuance. Sounds wonderful!

I think I’m going to call them “tips”, but it might not stick.

Inspirations