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

The Codex Schema

The HTML standard caters to every possible page on the web, from YouTube to wherever you buy your airplane tickets. As a result, the classification that it offers is very general. Codex was built specifically for journalism and therefore can employ a more specific taxonomy.

For example, the HTML standard indicates that we should use the <aside> element for tangential information. However, there’s no attempt to break that down any further, although different types of commonly used <aside> elements in news articles, such as a pull quote or a sidebar, are commonly used have radically different meanings and styles.

Here we offer some sensible class name choices as guidelines for use on Codex. Using this taxonomy means that you’ll be able to effortlessly switch articles between the built-in themes and your stories will be indexed properly in search and on home pages. When you use, for example, address.byline you’re not only styling that line of text, you’re adding metadata to the article.

If you’re a designer or developer building a Codex theme, you’ll want to make sure that you support the elements and class names below.

h1.hed This is the main headline for your article. It’s a bit longer than the article’s “title” but still often written in headlinese. Although HTML now allows many <h1> tags in a document, there should only be one hed in each article.
p.dek This is a second headline, directly below the main one. It’s optional but often desirable, providing more context. It should be a complete sentence with a subject and verb.
.intro This is a an introduction to the article, kind of like a fuller extension of the dek that might last for a paragraph or two. It often appears on top of an image that introduces the story in a visual way. The important thing is that this is not a part of the main flow of the story, but a setup for the action that takes place.
address.byline The author of the story. Note that you should not include the word “by” or any other prefix. These words can be added in CSS or outside the tag, but adding them inside means that the data for the story will be corrupted.
p.lede The first paragraph of the article. This class is optional, but can be used with the built-in themes to show the paragraph in a larger font, helping draw the reader into the text.
time.pubdate The publication date for the article. This is added automatically when you add { date } to the story.
p.section-start This is the paragraph that starts a new section. At the minimum, this class gives the paragraph some extra margin above it to signal the break . The first paragraph nested inside a <section> element will also have the same style in the built-in themes.
b.section-start This inline tag can be used for the first words of a new section as another visual clue to the reader that a break has occurred. This is traditionally done in bold or small caps.
h2.subhed A subhed is a small bit of text that serves as an internal headline for a section of the story. They are often useful to help break up longer texts where the reader may feel the desire to skip around or get some idea of what’s coming. Although the <h2> tag is optional, HTML standards say that we should use a header element to signal a new section and this may also be used by screen readers to create a document outline.
aside.editors-note An editor’s note sits outside of the main flow of the article and often is in a distinct voice. It provides some needed context about the article or it’s origin.
abbr.small HTML provides the <abbr> for all types of abbreviations, including shortened words like lb. for pound, initialisms like FBI and acronyms that are pronounced, like NATO. Abbreviations that are all capitals can benefit from a change to match the surrounding text. The built-in themes use the class name .small to achieve this.
.photo-credit All photos on the platform should be credited to their original sources, preferably with a link. This class can either be used at the end of a caption or by itself on an image.
aside.pullquote A piece of the article body that is shown at a large size to entice a reader browsing quickly and add visual interest to the page. Note that this must be a proper pull from the story and not simply a paragraph within the story shown in a larger font. You can aide the reader to know it’s not part of the flow by adding the class .right or .left which floats the paragraph beside the body copy on wider screens.
aside.pullquote .attribution Often when the pull quote is an actual quote from someone who isn’t the author, the attribution is included in a different style below it. Use the class .attribution inside a pull quote block. To do this, you’ll need to nest the quote and the attribution inside a block.
aside.sidebar A run of text on a tangential topic, typically no longer than a few paragraphs.