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

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

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

<div class="quote">
  <q>Mozilla is the best free alternative to Microsoft IE
     and it's faster to boot.</q>
  <cite>Rex Baldazo, C|Net</cite>
</div>

Epigraphs: <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.

<h2>What's MLP?</h2>
<div class="epigraph">
  <q>English is just another language.</q>
  <cite>Mozilla i18n and l10n Guidelines</cite>
</div>
<p>The Mozilla Organization works to create...</p>

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.

<p>These release notes describe system requirements,
   installation instructions, and known issues for Mozilla 1.2.1.</p>
<p class="note">Bug number references are included to
   provide more information about the specified issue or feature.</p>

Supplementary Sections: <div class="sidenote">

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 sidebars will typically be floated to the side, make sure the text reads reasonably without the float: it might set apart only by a different background or border (or nothing at all, e.g. on Lynx).

<p>The PLDHash implementation is a fairly low-level implementation,
  written in C. It is extremely flexible, but requires some time to
  understand and use. A basic guide is included here, but you should
  read ... in C++ code, as many potential casting errors are easily
  avoided.</p>
<p class="sidenote">The 'D' in PLDHash represents the "double-hashing"
   implementation of pldhash, which is how PLDHash resolves hash
   collisions.</p>
<p>You must declare an entry struct type, deriving from
   <code>PLDHashEntryHdr</code>. This entry struct should contain
   whatever data you wish to store in the hashtable (any pointer
   or fixed-length data type). <span class="note"> because of
   the double-hashing implementation, entries may move in memory when the
   hashtable is altered. If you need entry pointers to remain constant, you may
   want to consider using <a href="#PLHashTable">PLHashTable</a> instead.</p>

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

<div class="key-point">
  <h2>Mozilla 1.7 Beta is out!</h2>
  <p>This release has great new features and fixes...</p>
</div>

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>

<p class="important">Are you here because you have a problem
   with Netscape Communicator? If so, you're in the wrong place.
   Try visiting...</p>
        

regular emphasis: <em>

strong emphasis: <strong>

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.

Some <em>more</em>, <strong>more</strong>,
<strong class="stronger">more</strong>,
<strong class="very-strong">more emphasis</strong>!

Figures: <div class="figure">

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

Examples: <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 Usage: <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.)

<p>This example has too many methods:</p>
<pre class="bad code">
interface nsIFoo : nsISupports {
    long getLength();
    void setLength(in long length);
    long getColor();
};
</pre>
<p>The code below will generate the exact same C++ signature,
but is more script-friendly.</p>
<pre class="good code">
interface nsIFoo : nsISupports {
    attribute long length;
    readonly attribute long color;
};
</pre>

interface nsIFoo : nsISupports {
    long getLength();
    void setLength(in long length);
    long getColor();
};

interface nsIFoo : nsISupports {
    attribute long length;
    readonly attribute long color;
};

Bad Usage: <div class="bad example"> and <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: <kbd>

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

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

Variables and Placeholder Text: <var>

Use this to mark placeholders.

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

commands: <code class="command">

Use this to mark command names.

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

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>

Inline Code: <code>

Mark any inline fragments of code with this. It puts the text in a fixed-pitch font and triggers other code-styling switches (like turning off generated content styles).

Code Blocks: <pre class="code">

Mark all code blocks with this. In addition to visually setting the code 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.

Invalid code should be marked with bad code.

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

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

Text Screen Captures (Block Output): <pre class="screen"> and <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: <samp>

Use this to mark inline fragments of text output.

At the prompt, type <kbd>c:</kbd> and press <kbd>enter</kbd>.
The prompt should become <samp>C:\></samp>.

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 of <ol> only if the order of the entries in the list is insignificant.

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

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.

<ul class="snav">
  <li><a href="1.4/">1.4</a>
  <li><a href="1.5/">1.5</a>
  <li><a href="1.6/">1.6</a>
  <li><a href="1.7/">1.7</a>
</ul>

Breadcrumb (Hierarchy) Navigation: <p class="crumbs"><em>You are here:</em> with <a href="...">, > and <strong>

Breadcrumb navigation is for helping the visitor locate himself within a hierarchical structure and for providing links up to ancestor documents. It should be placed at the top of the document, before the main header. Each link is separated by a greater-than sign (>) to indicate the hierarchical relationship, and the name of the current page in <strong> ends the statement. Use short names for the link labels: the full title needn't be given. You must include the text "You are here:" in an <em> element as below for accessibility/usability reasons on non-graphical browsers; it will not show up on screen displays.

<p class="crumbs"><em>You are here:</em> <a href="../../">Contribute</a> &gt;
  <a href="../">Writing</a> &gt; <strong>Markup Reference</strong></p>

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. Its purpose is to warn the visitor that they're leaving mozilla.org's pages.