--- title: MDN style guide slug: MDN/Guidelines/Style_guide translation_of: MDN/Guidelines/Writing_style_guide ---
{{MDNSidebar}}

In an effort to display documentation in an organized, standardized and easy-to-read manner, the Mozilla Developer Network style guide describes how text should be organized, spelled, formatted, and so on. These are guidelines rather than strict rules. We are more interested in content than formatting, so don't feel obligated to learn the style guide before contributing. Do not be upset or surprised, however, if an industrious volunteer later edits your work to conform to this guide.

If you're looking for specifics of how a given type of page should be structured, see the MDN page layout guide.

The language aspects of this guide apply primarily to English-language documentation. Other languages may have (and are welcome to create) their own style guides. These should be published as subpages of the localization team's page.

For style standards that apply to content written for sites other than MDN, refer to the One Mozilla style guide.

Basics

Page titles

Page titles are used in search results and also used to structure the page hierarchy in the breadcrumb list at the top of the page. The page title (which is displayed at the top of the page and in the search results) can be different from the page "slug," which is the portion of the page's URL following "<locale>/docs/".

Title and heading capitalization

Page titles and section headings should use sentence-style capitalization (only capitalize the first word and proper nouns) rather than headline-style capitalization:

We have many older pages that were written before this style rule was established. Feel free to update them as needed if you like. We're gradually getting to them.

Choosing titles and slugs

Page slugs should be kept short; when creating a new level of hierarchy, the new level's component in the slug should generally just be a word or two.

Page titles, on the other hand, may be as long as you like, within reason, and they should be descriptive.

Creating new subtrees

When you need to add a number of articles about a topic or topic area, you will typically do so by creating a landing page, then adding subpages for each of the individual articles. The landing page should open with a paragraph or two describing the topic or technology, then provide a list of the subpages with descriptions of each page. You can automate the insertion of pages into the list using a number of macros we've created.

For example, consider the JavaScript guide, which is structured like this:

Try to avoid putting your article at the top of the hierarchy, which slows the site down and makes search and site navigation less effective.

Sections, paragraphs, and newlines

Use heading levels in decreasing order: {{HTMLElement("h2")}} then {{HTMLElement("h3")}} then {{HTMLElement("h4")}}, without skipping levels. H2 is the highest level allowed because H1 is reserved for the page title. If you need more than three or four levels of headers you should consider breaking up the article into several smaller articles with a landing page, linking them together using the {{TemplateLink("Next")}}, {{TemplateLink("Previous")}}, and {{TemplateLink("PreviousNext")}} macros.

The enter (or return) key on your keyboard starts a new paragraph. To insert a newline without a space, hold down the shift key while pressing enter.

Text formatting and styles

Use the "Formatting Styles" drop-down list to apply predefined styles to selected content.

Note: The "Note" style is used to call out important notes, like this one.
Warning: Similarly, the "Warning" style creates warning boxes like this.

Unless specifically instructed to do so, do not use the HTML style attribute to manually style content. If you can't do it using a predefined class, drop into {{IRCLink("mdn")}} and ask for help.

Code sample style and formatting

Tabs and line breaks

Use two spaces per tab in all code samples. Code should be indented cleanly, with open-brace ("{") characters on the same line as the statement that opens the block. For example:

if (condition) {
  /* handle the condition */
} else {
  /* handle the "else" case */
}

Long lines shouldn't be allowed to stretch off horizontally to the extent that they require horizontal scrolling to read. Instead, break at natural breaking points. Some examples follow:

if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION
       || class.YET_ANOTHER_CONDITION ) {
  /* something */
}

var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"]
                           .createInstance(Components.interfaces.nsIToolkitProfileService);

Inline code formatting

Use the "Code" button (labeled with two angle brackets "<>") to apply inline code-style formatting to function names, variable names, and method names (this uses the {{HTMLElement("code")}} element). For example, "the frenchText() function".

Method names should be followed by a pair of parentheses: doSomethingUseful(). This helps to differentiate methods from other code terms.

Syntax highlighting

Screenshot of the "syntax highlighting" menu.Entire lines (or multiple lines) of code should be formatted using syntax highlighting rather than the {{HTMLElement("code")}} element. Click the "pre" button in the toolbar to create the preformatted content box in which you'll then write your code. Then, with the text entry cursor inside the code box, select the appropriate language from the language list button to the right of the "pre" button, as seen in the screenshot to the right. The following example shows text with JavaScript formatting:

for (var i = 0, j = 9; i <= 9; i++, j--)
  document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);

If no appropriate transformation is available, use the pre tag without specifying a language ("No Highlight" in the language menu).

x = 42;

Styling HTML element references

There are various specific rules to follow when writing about HTML elements, in order to consistently describe the various components of elements, and to ensure that they're properly linked to detailed documentation.

Element names
Use the {{TemplateLink("HTMLElement")}} macro, which creates a link to the page for that element. For example, writing \{{HTMLElement("title")}} produces "{{HTMLElement("title")}}". If you don't want to create a link, enclose the name in angle brackets and use "Code (inline)" style (e.g., <title>).
Attribute names
Use bold face.
Attribute definitions
Use the {{TemplateLink("htmlattrdef")}} macro (e.g., \{{htmlattrdef("type")}}) for the definition term, so that it can be linked to from other pages, then use the {{TemplateLink("htmlattrxref")}} macro (e.g., \{{htmlattrxref("attr","element")}}) to reference attribute definitions.
Attribute values
Use "Code (inline)" style, and do not use quotation marks around strings, unless needed by the syntax of a code sample. E.g.: When the type attribute of an <input> element is set to email or tel ...
Labeling attributes
Use labels like {{HTMLVersionInline(5)}} thoughtfully. For example, use them next to the bold attribute name but not for every occurrence in your body text.

Latin abbreviations

In notes and parentheses

In running text

Meanings and English equivalents of Latin abbreviations

Abbrev Latin English
cf. confer compare
e.g. exempli gratia for example
et al. et alii and others
etc. et cetera and so forth, and so on
i.e. id est that is, in other words
N.B. nota bene note well
P.S. post scriptum postscript

Note: Always consider whether it's truly beneficial to use a Latin abbreviation. Some of these are used so rarely that many readers won't understand the meaning, and others are often confused with one another. And be sure that you use them correctly, if you choose to do so. For example, be careful not to confuse "e.g." with "i.e.", which is a common error.

Acronyms and abbreviations

Capitalization and periods

Use full capitals and delete periods in all acronyms and abbreviations, including organizations such as "US" and "UN".

Expansion

On the first mention of a term on a page, expand acronyms likely to be unfamiliar to users. When in doubt, expand it, or, better, link it to the article or glossary entry describing the technology.

Plurals of acronyms and abbreviations

For plurals of acronyms or abbreviations, add s. Don't use an apostrophe. Ever. Please.

Capitalization

Use standard English capitalization rules in body text, and capitalize "World Wide Web" and "Web".

Contractions

Use contractions (e.g. "don't", "can't", "shouldn't") if you prefer. We're not that formal!

Pluralization

Use English-style plurals, not the Latin- or Greek-influenced forms.

Hyphenation

Hyphenate compounds when the last letter of the prefix is a vowel and is the same as the first letter of the root.

Numbers and numerals

Dates

For dates (not including dates in code samples) use the format "January 1, 1990".

Alternately, you can use the YYYY/MM/DD format.

Decades

For decades, use the format "1990s". Don't use an apostrophe.

Plurals of numerals

For plurals of numerals add "s". Don't use an apostrophe.

Commas

In running text, use commas only in five-digit and larger numbers.

Punctuation

Serial comma

Use the serial comma. The serial (also known as "Oxford") comma is the comma that appears before the conjunction in a series of three or more items.

Note: This is in contrast to the One Mozilla style guide, which specifies that the serial comma is not to be used. MDN is an exception to this rule.

Spelling

For words with variant spellings, always use the first entry at Answers.com. Do not use variant spellings.

Terminology

Obsolete vs. deprecated

It's important to be clear on the difference between the terms obsolete and deprecated.

Obsolete:
On MDN, the term obsolete marks an API or technology that is not only no longer recommended, but also no longer implemented in the browser. For Mozilla-specific technologies, the API is no longer implemented in Mozilla code; for Web standard technology, the API or feature is no longer supported by current, commonly-used browsers.
Deprecated:
On MDN, the term deprecated marks an API or technology that is no longer recommended, but is still implemented and may still work. These technologies will in theory eventually become obsolete and be removed, so you should stop using them. For Mozilla-specific technologies, the API is still supported in Mozilla code; for Web standard technology, the API or feature has been removed or replaced in a recent version of the defining standard.

HTML elements

Use "elements" to refer to HTML and XML elements, rather than "tags". In addition, they should almost always be wrapped in "<>", and should be in the {{HTMLElement("code")}} style. Also, at least the first time you reference a given element in a section should use the {{TemplateLink("HTMLElement")}} macro, to create a link to the documentation for the element (unless you're writing within that element's reference document page).

User interface actions

In task sequences, describe user interface actions using the imperative mood. Identify the user interface element by its label and type.

Voice

While the active voice is generally preferred, the passive voice is also acceptable, given the informal feel of our content. Try to be consistent, though.

Wiki markup and usage

To automatically create a link to a Bugzilla bug, use this template:

\{{Bug(322603)}}

This results in:

{{Bug(322603)}}

For WebKit bugs, you can use this template:

\{{Webkitbug("322603")}}

This results in:

{{Webkitbug("322603")}}

Page tags

Tags provide meta information about a page and/or indicate that a page has specific improvements needed to its content. Every page in the wiki should have tags. You can find details on tagging in our How to properly tag pages guide.

The tagging interface lives at the bottom of a page while you're in edit mode, and looks something like this:

Screenshot of the UX for adding and removing tags on MDN

To add a tag, click in the edit box at the end of the tag list and type the tag name you wish to add. Tags will autocomplete as you type. Press enter (or return) to submit the new tag. Each article may have as many tags as needed. For example, an article about using JavaScript in AJAX programming might have both "JavaScript" and "AJAX" as tags.

To remove a tag, simply click the little "X" icon in the tag.

Tagging pages that need work

In addition to using tags to track information about the documentation's quality and content, we also use them to mark articles as needing specific types of work.

Tagging obsolete pages

Use the following tags for pages that are not current:

SEO summary

The SEO summary is a very short summary of the page. It will be reported as a summary of the article to robots crawling the site, and will then appear in search results for the page. It is also used by macros that automate the construction of landing pages inside MDN itself.

By default, the first pagragraph of the page is used as the SEO summary. However you can override this behavior by marking a section with the "SEO summary" style in the WYSIWYG editor.

Landing pages

Landing pages are pages at the root of a topic area of the site, such as the main CSS or HTML pages. They have a standard format that consists of three areas:

  1. A brief (typically one paragraph) overview of what the technology is and what it's used for. See {{anch("Writing a landing page overview")}} for tips.
  2. A two-column list of links with appropriate headings. See {{anch("Creating a page link list")}} for guidelines.
  3. An optional "Browser compatibility" section at the bottom of the page.

Creating a page link list

The link list section of an MDN landing page consists of two columns. These are created using the following HTML:

<div class="row topicpage-table">
  <div class="section">
    ... left column contents ...
  </div>
  <div class="section">
    ... right column contents ...
  </div>
</div>

The left-hand column should be a list of articles, with an <h2> header at the top of the left column explaining that it's a list of articles about the topic (for example "Documentation and tutorials about foo"); this header should use the CSS class "Documentation". Below that is a <dl> list of articles, with each article's link in a <dt> block and a brief one-or-two sentence summary of the article in the corresponding <dd> block.

The right-hand column should contain one or more of the following sections, in order:

Getting help from the community
This should provide information on Matrix rooms and mailing lists available about the topic. The heading should use the class "Community".
Tools
A list of tools the user can look at to help with the use of the technology described in this section of MDN. The heading should use the class "Tools".
Related topics
A list of links to landing pages for other, related, technologies of relevance. The heading should use the class "Related_Topics".

<<<finish this once we finalize the landing page standards>>>

Using, inserting images

It's sometimes helpful to provide an image in an article you create or modify, especially if the article is very technical. To include an image:

  1. Attach the desired image file to the article (at the bottom of every article in edit mode)
  2. Create an image in the WYSIWYG editor
  3. In the WYSIWYG editor in the drop-down list listing attachments, select the newly created attachment which is your image
  4. Press OK.

Other References

Preferred style guides

If you have questions about usage and style not covered here, we recommend referring to the Economist style guide or, failing that, the Chicago Manual of Style.

Preferred dictionary

For questions of spelling, please refer to Answers.com. The spell-checker for this site uses American English. Please do not use variant spellings (e.g., use honor rather than honour).

We will be expanding the guide over time, so if you have specific questions that aren't covered in this document, please send them to the MDC mailing list or project lead so we know what should be added.

MDN-specific

Language, grammar, spelling

If you're interested in improving your writing and editing skills, you may find the following resources to be helpful.