MDN 風格指南

為了讓文檔更加組織化、標準化而易於閱讀，MDN 風格指南描述了文本的組織方式、拼寫和格式等問題。這些規則只是指導方針而非強制規定。與格式相比，我們對內容更感興趣，因此在你做貢獻之前，大可不必因為沒有學習本指南而感到驚訝或沮喪，只管放手去做便是。勤勞的志願者們會編輯你的工作以符合本指南。

如果你在尋找頁面應當如何結構化的具體方式，參見 MDN 頁面配置指南。

在語言方面，本指南主要適用於英語文檔，其它語言可擁有（且歡迎創建）自己的風格指南。它們應作為當地語系化團隊頁面的子頁面發佈。

有關 MDN 以外網站內容的風格標準，請參考 Mozilla 風格指南。

基礎

維持整份文件的一致性是各大文件發表風格指南的基礎。以下段落將會列出這些基礎概念來協助您。

頁面標題

頁面標題會展示於搜索結果中，也可用於在頂部的麵包屑導航列中的層次結構以建構頁面。頁面標題可以與頁面“縮略名”不同。縮略名會出現在“<locale>/docs/”後，是頁面URL的一部分。

標題與頁首的大小寫

頁面標題與章節標題應使用一般句子的大小寫形式（只大寫句首字母和專有名詞）， 而非新聞式標題。

• 正確：“A new method for creating JavaScript rollovers”
• 錯誤：“A New Method for Creating JavaScript Rollovers”

有些舊的頁面編寫於本樣式規則定版之前。若你願意，可隨時更新它們。我們會逐漸完善它們。

選擇標題與簡述

頁面縮略名應保持簡短；當創建新的層級時， 該層次的縮略名通常應只由一兩個單詞組成。

至於頁面標題，只要在合理範圍內，長度可以隨意，不過它應當是描述性的。

創建新子樹

當你需要添加關於某個主題或主題範圍的文章時，一般可以創建一個登陸頁面，然後為這些文章分別添加子頁面。登陸頁面應當以一兩段對該主題或技術的描述開頭，接著提供一個子頁面的清單，並對每個子頁面做簡短的描述。你可以用一些我們創建的巨集來將頁面自動插入到該清單中。

以 JavaScript 指南為例，它的結構如下：

• JavaScript/指南 - 主內容表頁面
• JavaScript/指南/JavaScript 概述
• JavaScript/指南/函數
• JavaScript/指南/物件模型細節

請儘量避免將你的文章放在頂層，不然會拖慢網站的下載速度，降低網站導航和搜索的效率。

章節、段落與換行

請按照遞增順序使用標題級別：首先是 <h2>，其次是<h3>，接著是 <h4>，不要跳過級別。H2 是允許的最高級別，因為 H1 要留給頁面標題。若你需要超過四、五個級別的標題，請考慮將該文章拆分為幾篇更小的文章並創建登陸頁面，然後用巨集 Next、Previous 和 PreviousNext 將他們連結起來。

在你鍵盤上的 Enter (或 return) 鍵會開一個新的段落。如果希望插入新的一行中間沒有空白，就同時按下 Shift 和 Enter 鍵。

Don't create single subsections -- you don't subdivide a topic into one. It's either two subheadings or more or none at all. 

Don't have bumping heads, which are headings followed immediately by headings. Aside from looking horrible, it's helpful to readers if every heading has at least a brief intro after it to introduce the subsections beneath.

文本格式與樣式

請使用“樣式”下拉清單來為選中的內容應用預定義的樣式。

除非有明確指令，否則請勿使用 HTML 的 style 屬性來手動更改內容的風格。如果你無法使用預先定義的 class 來達成目的，就將他丟到 #mdn 以尋求協助。

範例程式的樣式與格式

縮排與換行

所有的程式碼範例，一個縮排使用兩個空白鍵。程式碼縮排要整潔、左大括號（ { ）和開展一段區域的宣稱同行。例如：

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

一行不能長到要橫向滾動才能閱讀，應當於自然斷點處換行。例如：

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

行內程式碼樣式

按下 Code 按鈕（標示為一對尖括號 <> ）套用到函式、變數、以及方法名稱的行內程式碼（這用到了 <code> 元素），例如 frenchText() 函式。

方法名稱要跟著一對小括號：doSomethingUseful()，這能讓該方法與其他程式碼術語做出辨別。

語法高亮

Entire lines (or multiple lines) of code should be formatted using syntax highlighting rather than the <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;

HTML 元素風格參考

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.

元素名

請使用 HTMLElement macro，它可以導向該元素的網頁連結。例如說，寫 {{HTMLElement("title")}} 就會產生 <title>。如果不想要有連結，使用尖括號把名字包起來 ，然後套用 Code (inline) 樣式（例如 <title>）。

屬性名

請使用 粗體

屬性定義

針對 definition term，請使用 htmlattrdef macro（例如 {{htmlattrdef("type")}}）so that it can be linked to from other pages, then use the htmlattrxref macro (e.g., {{htmlattrxref("attr","element")}}) to reference attribute definitions.

屬性值

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 HTML5 thoughtfully. For example, use them next to the bold attribute name but not for every occurrence in your body text.

拉丁語縮寫

在注記與括弧中

• 常見的拉丁縮寫（etc.、i.e.、e.g.）可以在括號表達、或注記內使用。這些縮寫都要用半形句點（.）。
  • 正確：Web browsers (e.g. Firefox) can be used ...
  • 錯誤：Web browsers e.g. Firefox can be used ...
  • 錯誤：Web browsers, e.g. Firefox, can be used ...
  • 錯誤：Web browsers, (eg: Firefox) can be used ...

在行文中

• 在普通行文中（也就是注記與括號以外的文字）請使用與該縮寫相等的文字表達。
  • 正確: ... web browsers, and so on.
  • 錯誤: ... web browsers, etc.
  • 正確: Web browsers such as Firefox can be used ...
  • 錯誤: Web browsers e.g. Firefox can be used ...

與拉丁文意義相同的中/英文

縮寫與簡稱

大小寫與點號

所有的縮寫與簡稱都要大寫、並把半形句點刪除，就算是「US」與「UN」之類的組織也一樣。

• 正確：XUL
• 錯誤：X.U.L.
• 錯誤：Xul

全名

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.

• Correct: "XUL (XML User Interface Language) is Mozilla's XML-based language..."
• Incorrect: "XUL is Mozilla's XML-based language..."

縮寫與簡寫的複數形式

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

• Correct: CD-ROMs
• Incorrect: CD-ROM's

大小寫

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

Keyboard keys should use sentence-style capitalization, not all-caps capitalization. For example, "Enter" not "ENTER."

縮寫

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

複數形式

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

• Correct: syllabuses, octopuses
• Incorrect: syllabi, octopi

連字號

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

• Correct: email, re-elect, co-op
• Incorrect: e-mail, reelect, coop

性別中立的用語

It is a good idea to use gender-neutral language in any kind of writing where gender is irrelevant to the subject matter, to make the text as inclusive as possible. So for example, if you are talking about the actions of a specific man, usage of he/his would be fine, but if the subject is a person of either gender, he/his isn't really appropriate.

Let's take the following example:

A confirmation dialog appears, asking the user if he allows the web page to make use of his web cam.

A confirmation dialog appears, asking the user if she allows the web page to make use of her web cam.

Both versions in this case are gender-specific. This could be fixed by using gender-neutral pronouns:

A confirmation dialog appears, asking the user if they allow the web page to make use of their web cam.

You can use both genders:

A confirmation dialog appears, asking the user if he or she allows the web page to make use of his/her web cam.

making the users plural:

A confirmation dialog appears, asking the users if they allow the web page to make use of their web cams.

The best solution, of course, is to rewrite and eliminate the pronouns completely:

A confirmation dialog appears, requesting the user's permission for web cam access.

A confirmation dialog box appears, which asks the user for permission to use the web cam.

The last way of dealing with the problem is arguably better, as it is not only grammatically more correct but removes some of the complexity associated with dealing with genders across different languages that may have wildly varying gender rules. This can make translation easier, both for readers reading English, then translating it into their own language as they read, and for localizers translating articles into their own language.

數字與數詞

日期

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

• Correct: February 24, 2006
• Incorrect: February 24th, 2006; 24 February, 2006; 24/02/2006

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

• Correct: 2006/02/24
• Incorrect: 02/24/2006; 24/02/2006; 02/24/06

年代

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

• Correct: 1990s
• Incorrect: 1990's

數詞的複數

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

• Correct: 486s
• Incorrect: 486's

逗號

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

• Correct: 4000; 54,000
• Incorrect: 4,000; 54000

標點符號

連續逗號

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.

• Correct: I will travel on trains, planes, and automobiles.
• Incorrect: I will travel on trains, planes and automobiles.

拼字

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

• Correct: localize, honor
• Incorrect: localise, honour

術語

棄用 vs. 過時

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

棄用：

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.

過時：

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

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 <code> style. Also, at least the first time you reference a given element in a section should use the HTMLElement macro, to create a link to the documentation for the element (unless you're writing within that element's reference document page).

• Correct: the <span> element
• Incorrect: the span tag

使用者介面動作

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

• Correct: Click the Edit button.
• Incorrect: Click Edit.

語態

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 語法與用處

外部連結

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:

WebKit bug 322603

頁面標籤

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:

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.

標記需要加工的頁面

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.

標記棄用的頁面

Use the following tags for pages that are not current:

• Junk: Use for spam, pages created by mistake, or content that is so bad that it should be deleted. Pages with this tag are deleted from time to time.
• Obsolete: Use for content that is technically superceded, but still valid in context. For example an HTML element that is obsolete in HTML5 is still valid in HTML 4.01. You can also use the obsolete_header macro to put a prominent banner on the topic.
• Archive: Use for content that is technically superceded and no longer useful. If possible, add a note to the topic referring readers to a more current topic. For example, a page that describes how to use the Mozilla CVS repository should refer readers to a current topic on using Mercurial repos. (If no corresponding current topic exists, use the NeedsUpdate tag, and add an explanation on the Talk page.) Pages with the Archive tag are eventually moved from the main content of MDN to the Archive section.

SEO 摘要

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 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 Writing a landing page overview for tips.
2. A two-column list of links with appropriate headings. See Creating a page link list for guidelines.
3. An optional "Browser compatibility" section at the bottom of the page.

創建頁面連結清單

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:

從社群尋求協助

This should provide information on IRC channels and mailing lists available about the topic. The heading should use the class "Community".

工具

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

相關主題

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

插入、使用圖片

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.

其它參考

首選風格指南

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.

首選詞典

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 特定資訊

• Custom CSS classes defined for all MDC pages.
• Custom templates created for use on MDC, with explanations.

語言、文法和拼字

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

• On Writing Well, by William Zinsser (Amazon link)
• Style: The Basics of Clarity and Grace, by Joseph Williams and Gregory Colomb (Amazon link)
• American Heritage Book of English Usage
• Common Errors in English
• English Grammar FAQ (alt.usage.english)
• Bob's quick guide to the apostrophe, you idiots (funny)
• Merriam-Webster's Concise Dictionary of English Usage (Amazon link): Scholarly but user-friendly, evidence-based advice; very good for non-native speakers, especially for preposition usage.