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 firstname.lastname@example.org.
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.|
Tabular information, like you’re reading now, belongs inside a
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
If your page has a block of links to other stories, use the
|<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.|
This is an interesting one since
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.|
|<sup>||Superscript, like an exponent.|
This is the inline equivalent of