You are viewing a degraded version of this page. Please use a supported browser for the best reading experience.

HTML Reference

This is a concise overview of the most common HTML elements used in articles on Codex. The web standards guide us in which tags or elements to give to specific pieces of text but this can quickly get to be a fraught and contentious area—often with zero outward difference for readers.

There are actually two competing standards that guide HTML and while they mostly agree, they can be serious disagreement as well. The W3C standard removed the <hgroup> element to wrap the headers at the top of a page, for instance, while the WHATWG standard still advocates it’s use. The former says you should only have one <h1> tag on the page while the other says it’s fine to only use <h1> for every heading. Curiously, neither one has a satisfactory system for subheadings below a main headline.

The reality is that the advent of modern web standards that dictate exactly how web content should look down to pixel accuracy mean that these differences are less important than when the Web was created and pages were often viewed in text terminals. They are still however crucially important for accessibility of your pages for blind or otherwise disabled readers. Search engines, other types of bots and the browsers themselves will also use these elements as the guide to your content.

The important thing here is to do your best. If you want to switch between themes on the platform and have your stories indexed properly, it’s probably more important that you use the class names in the Codex schema created for the built-in themes.

Codex has tried to nail the essentials here, but if you spot something amiss, please reach out to editors@codex.press.

Block-Level Elements

Most elements fall into either the category of “block” or “inline.” Block elements wrap to a new line of vertical space. Confusingly, there’s also “inline-block” elements which can change size but exist within a line of text but don’t w

<h1>, <h2> etc. These are headings. It makes sense to use a hierarchy of headline levels, with 1 as the biggest and 6 as the smallest. This isn’t essential, but each header should begin a new section of the document as in an outline however.
<figure> A <figure> element is used for content that is “self-contained.” This could be an image, for example, or a block of code. Note that the contents of the <figure> still appear in the main flow of the document and may not make sense in another location.
<figcaption> These are used inside a <figure> to provide a caption or legend.
<blockquote> Used for portions of a text that are quoted en masse from another document.
<aside> This is a piece of the article that is out of the main flow of content. In the built-in themes on Codex, the element is used for both pull quotes and sidebars.
<table> Tabular information, like you’re reading now, belongs inside a <table> element. Back in the bad old days of the web (read the ‘90s), tables were frequently used for layout, angering the semantic Gods and Goddesses.
<section> This is used for a “thematic grouping of content.” If this grouping is not thematic, it’s better to use a generic element such as <div>.
<nav> If your page has a block of links to other stories, use the <nav> element.
<ul> Unordered list, typically shown with bullet points.
<ol> Ordered list, which is shown with numbers beside it.
<header> Used for information at the top of the article such as headings or a logo.
<footer> On Codex, this is frequently used for information about the author or publication.
<div> This is an interesting one since <div> is purposefully generic and devoid of semantics. You should use it when none of the other elements seem to apply, or the grouping is made simply for aesthetic reasons. Given its generic nature and great utility, <div> is the default element when you nest a paragraph or group of paragraphs on Codex.

Inline Elements (Within Text)

There are more elements that can be used within paragraphs to provide meaning to bits of text within sentences.

<em> Emphasis. This indicates a verbal stress and typically is styled with italic. See also <strong>.
<strong> Typically denoted with bold text, this indicates strong importance, seriousness or urgency.
<small> Represents “side comments” such as fine print, but only for short runs within one paragraph.
<s> Strikethrough is used to indicate parts of text that have been corrected.
<cite> Citation, such as a book or film, either mentioned in passing or quoted in detail.
<i> The <i> element was originally created for “italic” but that, of course, has no semantic meaning. The element indicates “an alternate voice or mood... such as a taxonomic designation, a technical term, an idiomatic phrase from another language, transliteration, a thought, or a ship name in Western texts.”
<abbr> Abbreviation. Also used for acronyms, such as HTML.
<time> A time or date.
<b> Text that should be somehow more prominent but without conveying additional meaning, such as for the first words of a new section of an article.
<mark> Highlighted text.
<sup> Superscript, like an exponent.
<sub> Subscript.
<span> This is the inline equivalent of <div> — an element whose meaning is no meaning.