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 UseUse<strike>
to mark text that is no longer accurate or relevant.<s>
to mark text that is no longer accurate or relevant- Use
<ins>
and<del>
for funto 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
<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
- HTMHell —
markup from hell
- POSH — Microformats Wiki
- IETF BCP47 language subtag lookup
- Language Tags in HTML and XML
- The unreasonable effectiveness of simple HTML by
()Terence Eden