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 to indicate edited text
  • Use small for side-comments and fine print
  • Use time for datetime texts
  • Use samp for sample output from a computer program, e.g. 404 Not Found
  • Use kbd to present user input, e.g. Ctrl+Z
  • Use var for variables like x, y, and z
  • Add translate="no" for content that shouldn’t be translated

language

Always set the language to something because it is unknown by default.

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

meta

<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 the OpenGraph shit.

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

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 install -g html-validate
html-validate doc.html
html-validate -c /path/to/.htmlvalidate.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