Today I am super proud to announce that I have finally picked up the task of finishing my book titled, “HTML: A Comprehensive Guide”. I am writing the book in public and releasing it under the MIT license.
Learning HTML syntax is the simple part. The tedious part is learning which tags already exist, and which tags goes in which other tag (and which attributes they may (not) contain).
For that, always, ALWAYS go to the official HTML spec: WHATWG HTML.
HTML has not been maintained by WC3 (though they still do maintain CSS) and has been a “living standard” since HTML5 (2009-ish, IIRC).
I’ve read through the entire spec (using TTS, because only reading is boring) and learned a TON, because writing React straight out of the gate, without learning the HTML fundamentals first is a HUUUUGE pain.
/rant
Thank you for the feedback. I am also reading through the spec as a core part of writing the book. It is indeed critical to do so.
Web accessibility isn’t just about compliance; it’s about creating digital experiences that empower and include every user, regardless of their abilities.
Step 1: remove user agency.
<html lang="en"> <head> <base target="_blank" /> </head>I get that it’s hard to come up with a good example of using
<base>, but I wouldn’t show a user-hostile example before … cutting the element from Chapter 1 entirely. The only time I’ve ever used<base>was when I had to deploy multiple versions of a multi-page static site to a subdirectory for its staging environment, but to the public root for the production environment. Even then, the solution wasn’t, “use<base>,” it was, “sort shit out later with nginx.”Step 2: confuse the use case of anchors and buttons.
<body> <ul> <li><a class="native" href="add-book">Add Book</a></li> <li><a class="native" href="view">View Bookshelf</a></li> </ul> <ul> <li> <a href="https://example.com/dont-use-real-urls">Misery</a> </li> <li> <a href="https://example.com/especially-links-to-amazon-just-pick-a-real-bookstore">Carrie</a> </li> </ul> </body>I understand that it’s just an example but it’s never just an example. Use appropriate landmarks or break your snippets down to the point where it’s obvious that what you’re pointing out isn’t the whole thing. You don’t need
<body>or<ul>or<li>, just split the snippet in two, like this:<a href="/my-favorite-books">My Favorite Books</a><a href="https://example.com/some-book">Every Man For Himself and God Against All</a>Step 3: Introduce Javascript to restore the native functionality you broke in step one.
<script> document.addEventListener("click", (event) => { if (event.target.classList.contains("native")) { event.preventDefault(); window.location = event.target.href; } }); </script>Don’t do that. I mean, don’t really do any of this example, but really don’t do this last part. Adding
class="native"is as cumbersome as addingtarget="_blank", while also being more brittle. [I edited out a considerable amount of swearing here.] I think this is just a symptom of a bad example gone way too far.If the client insists on opening all external links in new tabs, get it in writing and then do this:
<base target="_blank" />let external_links = document.querySelectorAll('a[href^="http"]'); external_links.forEach((external_link) => { external_link.setAttribute('target', '_blank'); });You can use querySelectorAll with a prefix attribute selector like
'a[href^="http"]'instead of a typical class selector. This lets you grab all the anchors with hrefs that start with “http” without adding extra syntax where it doesn’t really belong. Once you’ve got your external links, iterate through that NodeList with forEach and tack ontarget="_blank"using setAttribute. That way, you’re not re-implementing default behavior, you’re only mildly annoying users with HCI devices, and if JS gets blocked all your links suddenly behave predictably.Even this is bad! Just don’t! It’s so easy to not!
Other notes
- You should probably start by explaining what an element is, then what an attribute is, then what a value is. Vocabulary is extremely important.
- When referencing elements, include the chevrons in the inline style.
<meta>vsmeta. If they have to guess, they’ll guess wrong. Suffix with “element” to really beat them over the head with it. - When referencing attributes, try to keep their values attached.
class="foreign". If you can’t, suffix it with “attribute.” - When referencing values, keep those quotes!
"false". - If it’s a book about HTML, don’t use JS. At all. Every time you reach for JS, stop. Like if you are about to write a self-invoking function to go and find invalid values of the
relattribute, for example, maybe don’t.
Thank you for the great feedback! This is one of the benefits of undertaking a project such as this in the open. I hear you with the
<base>element. I was in two minds whether I should even include it. I am thinking now that I should, but introduce it merely for completeness and recommend not using it. I wonder if it will ever be deprecated.
