Clean and consistent HTML markup

This article documents the conventions I use when writing HTML markup. Mostly in this blog but also in other situations where I have freedom and choice of markup.

General formatting

Respect Header Numbering! Always use correct <h1>, <h2>, ... tags: correct numbering. Only one (1) <h1> tag.

If you want to add emphasis on a word, use the <em> tag.

Technical formatting

When writing technical documents such as code reviews, instructions or technical documentation I always follow this markup guidelines.

Directory and names are marked with <u> tags: path/to/file.lisp.

When referring to general names (such as system names) I use <em> tags: my-system-name.

Semantical Structure

I try to avoid using markup for document structure as much as possible. When used, markup should in the first place be used for semantic markup and not for document styling. I'm writing documents that need to be read efficiently and clearly.

All my articles are written with the followng structure:

1. A <header> element with a <nav> element.
2. A <main> element with an <article> element. The article contents is placed in the <article> tag and has a series of headers. There is one <footer> element that contains author, date and contact information.
3. If I'm writing a long article, I wrap each <h2> in a separate <section> tag. This allows me to add an anchor to each section and I can easily link to a specific section. This can be repeated for <h3> sections as wel if required.