Describing the Semantics of My Site

Paying Attention to the HTML

Readers of my site may notice the Cascading Stylesheet (CSS 📖) styles and Hypertext Markup Language (HTML 📖) markup. I have spent time ensuring that the markup is in good order; leveraging software automation to help the process. However, I haven’t explained my intention/meaning of these.

Commentary and Marginalia

There are the long-standing margin notes and side notes. Both have the ARIA-role of “note” and leverage the small tag. Per the small tag’s Mozilla Developer Network documentation: this element “represents side-comments and small print, like copyright and legal text, independent of its styled presentation.”

The side note has an auto-incrementing number that associates the note with the specific place in the text. Most notably it is a comment that is part of the paragraph, albeit as marginalia.

With that in mind, the side note should not be a block element.

The margin note is it’s own paragraph or paragraphs; a bit of commentary that is not directly related to a paragraph but which relates. And the margin note can leverage the aside tag.

New to my commentary and marginalia is the inline comments. I intend for this section to be another form of commentary. It is not semantically an aside, as it is part of the main document; however it is representing a different voice or perspective.

Terms and Definitions

There are five primary tags that require discussion: abbr, cite, dfn, dl, and i.

I write across several different domains, and in those domains there are many acronyms. I maintain a personal glossary of those terms and expose them on the Glossary of Terms for Take on Rules page. The first time on a page I render the acronym, I often include the title. Thereafter, I only render the acronym, via the abbr tag. I use a Hugo 📖 shortcode to manage this rendering. Here is my implementation of the glossary shortcode. Fair warning, it’s rather complicated. Compared to the abbr tag, most other tags of this group are conceptually easier.

I use the cite tag to indicate the title of a creative work.

I use the dfn tag to indicate that the subsequent text is the definition of the word or words that are in the dfn tag.

The dl tag, or description/definition list is akin to the more ubiquitous ordered/unordered list. The main difference is that each list item has a term, akin to dfn, and one or more details for that term.

Last of this group is the i tag. This is where Mozilla Developer Networks documentation is most helpful:

The <i> HTML element represents a range of text that is set off from the normal text for some reason, such as idiomatic text, technical terms, taxonomical designations, among others. Historically, these have been presented using italicized type, which is the original source of the <i> naming of this element.

My use of the i tag is for idiomatic words. My use of the em tag is for emphasis. In most cases I add a .dfn class to my i tag and my site’s CSS styles the dfn tag and .dfn class the same. In other words, I am somewhat saying the i tag is a defined term but I won’t be providing you with the definition.


I make use of the time element, providing a textual version of a date as well as machine readable format.

In a few cases I’ll use the sup or sub tags to indicate superscript and subscript.

I also make extensive use of the table and associated tags; because sometimes tabular is the correct semantics.

And last, there is the lowly · (e.g. the &middot HTML entity). From “The middle dot (a.k.a. interpunct) is often used as a list separator…”

I use the · as a list separator for elements in the header and footer sections. I leverage ARIA role attributes to semantically name elements as list items. However I don’t use the li element in the header (and it’s parent ul or ol element).

Why not use an ol or ul in the header? Turn off the styles of my site. Were I to use ol or ul for my header and footer, those items would render as block elements. Which, if you have lots of header elements creates what I consider to be an ugly experience. For example go to and turn off styles. By leveraging a mix of ARIA roles and the lowly &middot entity, I provide both lists and visual separators; all while not adding unnecessary line breaks because I chose the semantic tag of ol or ul.


In adopting semantic HTML and supplementary ARIA roles, my hope is to provide an accessible reading experience. One that considers both the visual cues as well as cues provided by assistive technology.