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 ori
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, usestrong
. 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 UseUsestrike
to mark text that is no longer accurate or relevant.s
to mark text that is no longer accurate or relevant- Use
ins
anddel
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
- HTMLHell —
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