Markup Reference


The purpose of this document is to define a rich vocabulary of semantic classes whose presentation can be specified in site-wide style sheets—enough to be able to write a long, involved, well-styled document without once writing a CSS rule. These classes take the place of the old presentation templates; the presentation is now defined in the site style sheets, allowing the markup to remain semantic. This simplifies the HTML coder's job, allows a greater flexibility in styling pages, and ensures consistent formatting conventions throughout the site.

These classes are defined to be used on an as-needed basis. If you don't need them, you don't have to learn or use them. But if you find yourself needing presentational markup or CSS, check here first—maybe what you're looking for is already defined. (If it's not, then maybe it should be. If you think your style rules would be useful for other authors, file a bug report against

  1. General Structure
  2. Quotations
  3. Notes of All Sorts
  4. Emphasis
  5. Examples and Figures
  6. Computers
  7. Navigation

General Structure


<p> and <div class="para">

Use <p> to mark paragraphs. Use the tags to enclose paragraphs, not to separate them.

<div class="para"> is for paragraphs that logically enclose block-level elements not allowed in <p> by the HTML DTD. For example, one might have a paragraph split by a <blockquote>. In this case, each half of the paragraph gets a separate <p> and the whole construct is enclosed by <div class="para">. Don't use it for inline figures you want rendered as blocks, though—<img> is allowed in <p>, and the style sheets can render it as a block even in NS4.x.

<div class="para">
    <p>When writing technical documentation, especially online
    documentation, strict organization assumes a particularly
    important role. The reader is often there only to find some
    specific piece of information, and typically scans rather than
    peruses the text. To make this easier,</p>
        <li>subdivide your document and outline it with headings
        <li>organize a strong structure
        <li>use bulleted lists
        <li>write concisely; don't ramble
        <li>get to the point first, then elaborate
        <li>don't write long introductions except in "Introduction"
        <li>give a clear explanation
        <li>and use specific examples to illustrate the text. 
           (An example is worth a thousand words.)
    <p>You want the main points of your writing to stick out so
    that the reader can find the right section quickly and easily.
    Snag them first, then explain.</p>


<div class="section">

Use <div class="section"> to mark sections within a document. Enclose both the heading and the content. Sections are typically indented slightly, compared to the surrounding text.

<div class="section">
  <h2><a name="structure">General Structure</a></h2>

Data Tables

<table class="data">

Use this class to indicate that an HTML table is a data table so style sheets can add colors and borders. (There are still a lot of layout tables on, so we can't just color all tables indiscriminately.) If you want even/odd stripes, use the even and odd classes (on <tr>) instead of creating your own.


Block Quotes

<blockquote> with <address>

Use this for block quotes: paragraphs or other block-level content. An attribution can be given with <address> just before the closing tag.

<blockquote cite="">
  <p>The BLOCKQUOTE element contains text quoted from another source.</p>
  <p>A typical rendering might be a slight extra left and right indent,
           and/or italic font. The BLOCKQUOTE typically provides space above
           and below the quote.</p>
  <p>Single-font rendition may reflect the quotation style of Internet
           mail by putting a vertical line of graphic characters, such as the
           greater than symbol (>), in the left margin.</>
  <address><a href="">HTML

Short Quotes

<div class="quote"> with <q> and <cite>

Use this for short quotes: phrases to sentences, not enough to warrant a block quote. The quoted text should be in <q>, the attribution, if any, in a following <cite>


<blockquote class="epigraph"> or <div class="epigraph">

An epigraph is a motto or quotation, usually at the beginning of a composition, that sets forth a theme. Usage for the epigraph tags is as for <blockquote> and <div class="quote">, described above.

Notes of all Sorts

Writer's/Editor's Comments

<div class="remark"> and <span class="remark">

Use this to designate a writer or editor's comments in a draft. (This is also used to designate comments in code blocks.) Don't add punctuation to set it off; the style sheet may generate them.

This flag is set if the combined area of a frame's children extend
past the frame's bounding box. <span class="remark">What 
is a frame's "bounding box"?)</span> If this flag is set, then...

Generic "Note"s

<span class="note">, <p class="note">, and <div class="note">

Use this to mark a note. Style sheets will generate the text "Note: " before the note and will typically also introduce some other font or color change.

Supplementary Sections

<div class="sidebar">

Use this for short sections of information (or links) that aren't directly relevant to the main text and thus should be set apart from the main flow of the discussion. While it will typically be floated to the side, don't rely on it for layout purposes: it might set apart only by a different background or border.

Key Notes

<div class="key-point">

Use this to "box" key sections in the main flow of the text—to make them stand out or set them apart. (Use important, though, for critical notices.)

Important (i.e. Must Read) Notices

<* class="important">

Use this to indicate an important notice—something that must not be missed. important is typically rendered in a bigger font and/or with bright coloring. Make sure the text is also encased in a <strong>


Regular Emphasis


Strong Emphasis


Stronger Emphasis

<strong class="stronger">

Very Strong Emphasis

<strong class="very-strong">

These indicate varying levels of emphasis. For reference, the typical presentation goes italic, bold, bold italic, bold uppercase.

Examples and Figures


< div class="figure">

Use this to mark images used as figures or diagrams. A figure is typically rendered as a centered block.


<div class="example">

Use this for any type of example. (But don't forget to enclose code snippets in code blocks.) You can give caption text with the title attribute.

Good Example

<div class="good example"> and <pre class="good code">

Use the good class to specifically mark examples and code as good usage. (If the code sample is in a good example, it doesn't need its own good.)

Bad Example

<div class="bad example"> <pre class="bad code">

Use the bad class to specifically mark examples and code as invalid or bad usage. (If the code sample is in a bad example, it doesn't need its own bad.)


Keyboard Input


Text to be entered by the user — use this for text the user must type and for marking key combinations.

Push Esc and type :wq.

<p>Push <kbd>Esc</kbd> and type <kbd>:wq</kbd>.</p>

Variables and Placeholder Text


Use this to mark placeholders.

<p>Push <kbd>Esc</kbd> and type <kbd>:w <var>filename</var></kbd>.</p>


<code class="command">

Use this to mark command names.

<p>The <code class="command">ls</code> command lists all files in the current directory.</p>

Filenames and URIs

<code class="filename">

Use this for filenames, paths, and URIs.

Save the file as <code class="filename">/home/<var>your_username</var>/.bashrc</code>

Code Blocks

<pre class="code">

Inline Code


Mark all code fragments with one of these. In addition to visually setting the code fragment off from the rest of the text, it also suggests a syntax-highlighting mode to the style sheet for markup such as <span class="remark"> and <var>, and disables generated content. Use emphasis to highlight important fragments.

Text Screen Captures (Block Output)

<pre class="screen"> <div class="screen">

Use the screen class on a pre to mark a block of computer text output, such as a screen capture from a terminal window or an ASCII-art GUI design. You can also set it on a <div> to use HTML markup to express the output, as for page code examples.

Inline Output


Use this to mark inline fragments of text output.


Table of Contents

<ol class="toc">, <ul class="toc"> and <dl class="toc">

"toc" marks a list as a table of contents. Use <ol> for a simple single- or multi-level listing. (For multi-level listings, only set the class on the outermost list.) Use <ul> instead only if the order of the entries in the list is insignificant.

When used with <dl>, the term (<dt>) gives the section name and the definition (<dd>) gives a short description or abstract of that section.

Local (Mini) Navigation

<ul class="snav">

snav is for "short navigation" or "sectional navigation", whichever you prefer, and is intended to be a short list of local navigation links (which might all even link to parts of the same page). It is to be used at the discretion of the individual page author (as opposed to a template designer), and it is not a proper table of contents.

External (Extra-site) References

<a class="ex-ref">

Use ex-ref to denote links to another site. For example, a link to MozillaZine would be marked as ex-ref. Typical formatting for an ex-ref link is slightly different from a regular link. It's purpose is to warn the visitor that they're leaving's pages.