html

HTML is easy to learn, but hard to get right.

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

language

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

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

meta

Forget OpenGraph.

<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">

For light and dark themes. Some browsers will 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 any assistance from some generative AI:

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

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>five
  <li>six
  <li value="8">eight
</ol>

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. Their 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. All custom elements behave like inline ones by default. Just don’t use them over semantic HTML.

<v-n>1234</v-n>

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 I disabled the doctype-style rule to allow lowercase doctype. It’s cuter that way.

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

resources