The making of HTML for People

October 27, 2024

On Thursday, October 10, I released HTML for People into the wild. I emailed the 300-ish people who had signed up to be notified and then posted on Mastodon. The response blew me away. In a couple of days, my post got boosted over 2,000 times. The URL made it to the front page of Hacker News. Analytics shows tens of thousands of visits to the site.

Moreover, I started getting messages, not only from tech-savvy developers who already know how to make websites but from people just getting started. I was ecstatic to see those because I feared I would write this web book (as I call it), and it wouldn’t reach beyond my circle of developers.

It has been a few weeks, so it’s time to formally introduce it on my blog and provide a little bit of director’s commentary.

HTML for people unaccustomed to coding

I have forgotten why the name popped into my head, but my notes show that I wrote down the idea in January. “HTML for people,” I wrote, “is an idea for a radically non-technical (as much as possible) guide for teaching regular people how to make their own websites from scratch and put them on the internet.”

I introduce HTML not as a “coding language” but as a document format like Word. Then, I slowly teach about tags, structure, and semantic content (but without using words like “semantic”). Throughout the book, I guide the reader through building a personal website using HTML and Simple.css.

I intentionally avoid discussing CSS as much as possible, only really delving into it in an appendix that I call a bonus chapter. These bonus chapters go more in-depth on styling and introduce the PHP include statement as a way of composing HTML.

I published the book as a website and made it freely available. I licensed the code and content under a Creative Commons license.

Motivation

I joked on Mastodon that my selfish motivation was that, having deleted my Facebook account in 2017, I now needed everyone to have a personal webpage. I was only half joking.

I feel a strong sense of nostalgia when I think about my younger self learning HTML in the 2000s. It was a time of both frustration and limitless possibility. I developed an interest in making websites in high school. At the time, I was using whatever free WYSIWYG (“what you see is what you get”) editor I could get my hands on. But I quickly got fed up with being unable to implement the designs I had in my head. I knew I needed to learn how to make webpages for real. Here is a screenshot of my freeware gaming site, which I converted from some free website editor to handwritten HTML.

On the one hand, it was difficult because I was learning about something completely foreign—I had never done any coding or programming. As I was learning, my design abilities were extremely limited. But at the same time, I unlocked a newfound joy in creating something clean and fresh. My mind was blown by the realization that websites were just text files on a computer. Once I realized that, I couldn’t get enough of the make-a-change-and-hit-refresh positive feedback loop.

My websites were mine. I had not joined any social networks when I was first learning HTML. I was never really interested in MySpace,^[1] and Facebook had yet to make it to my university (remember when it was universities only?). I knew about blogging, but now that I could write HTML directly, even a blog on Blogger felt somehow less mine. It’s difficult to overstate how proud I was to publish on the internet, even if the content was silly or inconsequential.

This mentality of ownership has aged better than I could have imagined. In a world where most people publish on the internet inside walled gardens that mine their inhabitants for profit, the humble personal website becomes even rarer a gem. I wanted to tap into that nostalgia of my early years. I wanted to expose more people to the fundamental, direct way of publishing on the web. I wanted to show that anyone could do it—not just professional developers.

From zero to internet

I was riffing with Sara on Mastodon when I first posted the phrase “HTML for people.” I wanted a practical guide to putting a page on the web in its simplest form. What is the fastest way to go from nothing to having a page on the internet that you created yourself?

I was deeply inspired by this old CSS-Tricks post where Chris Coyier gives a straightforward, practical answer to how to get started in web design. If you follow his steps, you end up with a webpage on the internet. You don’t get drowned in theory or concepts. I wanted that directness but for pure HTML. It wasn’t so much how to get started in web design as a profession, but thinking of HTML as a viable way for anyone with a passing interest to make a website.

I wanted to approach HTML from the personal rather than the technical side, and I wanted it to be immediately valuable. That’s why, in the very first chapter, there isn’t a single HTML tag! We just write some text in an HTML file and publish it. It goes from file-on-your-computer to live webpage in as few steps as possible.

Only after publishing the first plain webpage do I discuss adding HTML tags. But after making a few basic pages, I wanted to introduce styling without teaching CSS.^[2] Fortunately, Simple.css exists. In fact, there are many classless frameworks out there, and I’ve been fascinated by them for quite some time.

The book could be renamed How to Build a Website with Simple.css and would still be accurate. That’s really what this book became. I’m grateful to Kev Quirk and contributors for the Simple.css project. I believe it was the perfect framework for this scenario because it makes writing HTML fun.

Generating hype

I usually don’t publicize things I am working on for better or worse (mostly for worse). I have been a “build it and they will come” kind of developer for years. But for this project, I just decided to throw up a landing page Adam Newbold-style with a title and description. I added an email signup, too. I was so sure that the interest would be minimal that I wrote a short PHP script to save the emails to a text file rather than use some kind of email list service. I figured I would just email each person individually.

I posted about the idea on Mastodon and threw the landing page out there. To my surprise, more than a few people seemed interested. The number of subscribers crept up throughout the summer as I worked. Nearly 300 people had signed up to be notified of the book’s release.

I find it scary to promise something I’m making. I don’t like the pressure. What if I fail to deliver? What if I decide I hate the project and don’t want to release it after all? What if everyone finds out I’m an imposter?

But it wasn’t so scary after all. People liked the idea. I found the early feedback motivating, and it helped me push through the…

Gruntwork

I had the idea near the beginning of the year, but it was April or so before I started in earnest. The tricky bit was building the same site I was teaching how to build and getting screenshots along the way. I tried keeping a Git repo with branches at each stage, but it got out of hand after a point.

Along with that was the writing. I’m a slow typer because I mostly use an onscreen keyboard. I spent just about every weekend during the summer writing.

In September, I picked up a Grammarly subscription and proofread every chapter. This was eye-opening. I never realized how much I leaned on certain words or phrases as a crutch. Grammarly has some annoyances,^[3] but it did improve my writing.

After proofreading, I began processing the 70+ images I used in the book—most of them screenshots. I knew I was going to need to supply alt-text for these images, but I also knew that it would take me ages to type them out by hand (screenshots, in particular, are challenging to write alt-text for because I need to describe the same nuanced information I’m conveying to sighted readers—that is, how changes to the code result in changes to the rendered webpage).

I used an AI tool that could look at an image and generate alt-text. It worked okay, and it got 80% of the typing done for me. I read and edited each one as necessary to avoid blindly throwing AI garbage into my content.^[4]

Finally, I scaled, crushed, and converted the hi-res PNG screenshots into smaller WebP images. This was my first time actively using WebP, and I was shocked at how small the file sizes were. I used the handy Squash app (also available on Setapp—affiliate link) to process the images in batches.

After proofing and processing images, I decided to “splurge” by commissioning some artwork. While I originally planned not to spend much money on this project, I felt that some friendly artwork would go a long way toward softening the blow for beginners who might feel intimidated.

I had previously been a customer of Andy Carolan, known in the fediverse for his avatar commissions. But he also has an extensive portfolio of quality work. I commissioned the homepage illustration, the development of a mascot, and supporting assets like the open graph preview image.

Even as I was procuring art, I failed to realize just how vital a good open graph preview image is. There’s a reason many YouTubers put so much effort into making thumbnails—they work. I attribute the book’s launch-day success primarily to the quality of the preview thumbnail. It enticed people into clicking. Yes, I had to back it up with content people enjoyed, but the thumbnail brought people through the door.

Building the site

For me, this was the fun part. I revel in sweating the details of typography and page design. I built the site using Eleventy, which has become my go-to for static websites. I chose typefaces from the excellent MB Type. I tweaked the typography relentlessly, even changing the heading font at the last minute before launching!

I have come to loathe frontend build steps, so other than Eleventy, I didn’t use any bundler for assets. I used vanilla CSS and, in a few spots, vanilla JavaScript. What a breath of fresh air. Look, I’m not saying bundlers and tooling don’t have their place—sometimes they’re handy—but I believe they are vastly overused in modern web development. I have a lot of opinions about the maintainability, sustainability, and ergonomics of frontend tooling, but that’s a blog post for another day.

After finalizing the site build (and adding some interactive Easter eggs to the artwork), I did one final manual proofreading. On the morning of October 10, I hit the launch button and posted the link on Mastodon.

Launch-day shenanigans

I initially deployed the site to Cloudflare Pages, which I’ve found to be the dead simplest way to deploy an Eleventy site from a Git repo. I set up the DNS, and everything seemed to work. Almost immediately, I started receiving reports that some of the chapters, when navigated to via the main menu, were downloading a file rather than displaying a webpage. Wha?

I frantically re-deployed the site to my longtime, trusty shared host, and it seemed to work normally. After screwing with the DNS, including a brief period where I caused an infinite redirect loop, I successfully pointed the domain back at my shared host with Cloudflare features disabled. Fortunately, static sites are resilient, and that setup got me through the launch-day traffic.

I blamed Cloudflare at first, but—shocker—I’m the problem; it’s me. I misconfigured some of my Eleventy templates, causing them to output files without file extensions. Cloudflare, understandably, didn’t know what to do with those files. I was lucky that my shared host decided to serve them as HTML. Anyway, I’ve since fixed my configuration, and now I’ve moved everything back to Cloudflare Pages—I think that’s better for the international readers who might experience latency from my shared host.^[5]

Feedback, discussion, and the future

I enjoyed reading the discussions happening at various places online, in particular, MetaFilter and Hacker News. And, of course, Mastodon. I’m grateful for all the feedback, suggestions, and corrections. A few people filed issues on GitHub and even submitted PRs!

Internationalization

I’ve had many requests for translated versions of the book. I’m new at this and not sure how to proceed. I would love to have translated versions and am happy to host them. I need to update the repo’s readme with something about contributing translations, but in the meantime, if you are interested in contributing translations, please email me.

I’m thinking a translation could go into a subfolder, for example, /es/. We could use the same images, or if someone wants to try to get language-specific screenshots, I’d be good with that as well. It’s a lot of work, though! I would be willing to list contributors on the translated pages and allow donation links.

Downloadable PDF

People also asked for a downloadable version. I put up a quick everything-on-one-page printable version, but I’d love to offer a nice PDF version and possibly an ePub version.

It would take some work, and if I do it, it will probably be for sale on Gumroad or something.

Video course

I nearly decided to tack on a video course at the last minute. My coworkers will tell you I tend to sabotage myself with scope creep.^[6] Fortunately, I talked myself out of delaying the web book.

That said, I’m still considering a video series. If that sounds like something you’d be interested in, let me know. I do have difficulty typing, and I’m self-conscious about it when people are watching (because it’s slow, and I don’t want to bore people), so I’m not sure about the logistics of it. If I end up doing this, I’m leaning towards it being free on YouTube.

Will you write more For People books?

Maybe! I have a special, nostalgic place in my heart for JavaScript (not the complex FAANG kind, but the homemade, fun kind). But it’s not as easily approachable as HTML. I’m not sure I have much to offer beyond the many, many JavaScript resources that are out there already. I did buy the domain, though, because obviously I did.

But keep your eyes on a few that are coming from some smart peeps I know!

• CSS for People by Annie
• PHP for People by Neatnik