avanier's banner

html

HTML is easy to learn and hard to get right.

language

Set the language to something because it would be unknown by default.

<!doctype html>
<html lang="en">

guidelines

  • Have only one <main> per page
  • Have only one <h1> per page
  • Use <em> for emphasis. Do not use it or <i> simply to italicise
  • Use <i> for text that is set off from the others, i.e. thoughts, transliterations, idiomatic terms from other languages, etc.
  • Use <b> to draw attention to text, but if it’s of strong importance, use <strong>. Use CSS instead if you just want to visually bolden text without any semantic reason
  • Use <mark> to highlight text
  • Use <q> for short, inline quotes, <blockquote> for long ones
  • Use <abbr> for abbreviations and acronyms
  • Use <dfn> for definitions
  • Use <strike> to mark text that is no longer accurate or relevant. Use <s> to mark text that is no longer accurate or relevant
  • Use <ins> and <del> for fun to indicate edited text
  • Use <small> for side-comments and fine print
  • Use <time> for datetime texts
  • Use <samp> for sample output from software, e.g. 404 Not Found
  • Use <kbd> to present user input, e.g. Ctrl+Z
  • Use <var> for variables, e.g. x, y, z
  • Add translate="no" for content that shouldn’t be translated
  • Unless it’s for a code golf, don’t bother with unquoted attribute value syntax and optional tags

meta

The basics:

<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="author" content="avanier">
<meta name="description" content="about this page">

Forget Open Graph. Open Graph is a hellspawn of Facebook, but Mastodon makes use of this protocol to generate rich preview cards from links so…

TODO: JSON-LD can also be used to replace it (except og:image and og:image:alt). See link_details_extractor.rb

<meta property="og:title" content="HTML">
<meta property="og:description" content="notes on HTML">
<meta property="og:type" content="article">
<meta property="og:site_name" content="avanier.dev">
<meta property="og:site" content="https://avanier.dev">
<meta property="og:author" content="Josh Avanier">
<meta property="og:url" content="https://avanier.dev/html">
<meta property="og:image" content="https://avanier.dev/m/1.png">
<meta property="og:image:alt" content="Logo">

For light and dark themes. Some browsers use these values to customise the browser user interface accordingly.

<meta name="color-scheme" content="light dark">
<meta name="theme-color" media="(prefers-colors-scheme: light)" content="#f8f8f8">
<meta name="theme-color" media="(prefers-colors-scheme: dark)" content="#030303">

It’s insane that it has to come to this, but here are David Copeland's AI Content Declaration meta tags to declare that your site was made without assistance from some Gen-AI:

<meta itemprop="ai-content-declaration:version" content="1.0.0">
<meta itemprop="ai-content-declaration:level" content="none">

For geotagging pages. Use ISO 3166-2 for geo.region.

<meta name="ICBM" content="43.1575,77.058611">
<!-- or -->
<meta name="geo.position" content="43.1575;77.058611">
<meta name="geo.region" content="KZ-75">
<meta name="geo.placename" content="Medeu, Almaty, Kazakhstan">

If the page has NSFW content:

<meta name="rating" content="adult">

To prevent Pinterest saves:

<meta name="pinterest" content="nopin">

void elements

According to the HTML Standard § Start tags, a solidus in a void element has no effect. In other words, self-closing tags like <meta> don’t need to be written as <meta ... />, although you may continue to do so if you need XHTML compatibility.

lists

You can use start to set a custom counter start for ordered lists. A list item’s number value can also be overridden with value.

<ol start="5">
  <li>the fifth</li>
  <li>the sixth</li>
  <li value="8">the eighth</li>
</ol>
  1. the fifth
  2. the sixth
  3. the eighth

data attributes

You can add custom attributes to tags. I use these throughout the site for tooltips, timestamps, and such.

<p id="example" data-key="value">…</p>
<script>
  const p = document.getElementById("example");
  console.log(p.dataset.key); // "value"
</script>

custom elements

HTML allows custom elements, and you don’t need JS to use them. The tag names must follow these rules:

  • Start with ASCII
  • Have at least one hyphen-minus (-)
  • Numbers and emojis are allowed after the initial letter
  • lowercase letters only

All custom elements need to have closing tags and behave like inline ones by default. Just don’t use them over semantic HTML.

<n-umber>1234</n-umber>

validation

I use html-validate.

pnpm i -g html-validate
html-validate doc.html
html-validate -c /path/to/config.json doc.html

Here’s the config I use — I’m using the recommended and accessibility defaults, but with the doctype-style rule disabled to allow lowercase doctype. It’s cuter that way.

{
  "extends": ["html-validate:recommended", "html-validate:a11y"],
  "rules": { "doctype-style": "off" }
}

resources