mozilla.org Markup Reference

Paragraphs

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>
    <ul>
        <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"
            sections
        <li>give a clear explanation
        <li>and use specific examples to illustrate the text. 
           (An example is worth a thousand words.)
    </ul>
    <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>
        

Sections

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>
  ...
</div>
        

Data Tables

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 mozilla.org, 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

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="http://www.faqs.org/rfcs/rfc1866.html">
  <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="http://www.faqs.org/rfcs/rfc1866.html">HTML
                 2.0</a></address>
</blockquote>
        

Short Quotes

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>

Epigraphs

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.

Writer's/Editor's Comments

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

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

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

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

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

Very Strong Emphasis

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

Figures

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

Examples

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

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

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.

<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>
        

Commands

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

Use this for filenames, paths, and URIs.

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

Code Blocks

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)

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

"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

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

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 mozilla.org's pages.