정돈되고 일관적이며 읽기 쉬운 문서를 제공하고자, MDN 웹 문서 스타일 안내서는 글의 정렬, 철자, 서식 방법 등을 정리합니다. 이 가이드는 엄격한 규칙이라기보다 가이드라인입니다. 우리는 형식보다는 내용에 더 관심이 있습니다. 그러니 기여하기 전에 스타일 가이드를 배워야 한다는 부담을 느끼시지 않아도 됩니다. 하지만 나중에 다른 부지런한 지원자가 이 가이드를 따라 당신의 작업물을 편집할 수 있습니다. 만약 그런 일이 벌어지더라도 화내거나 놀라지 마세요.
이 가이드의 언어적 측면의 내용은 영문을 위주로 작성되었습니다. 기타 다른 언어는 언어만의 고유한 스타일 가이드를 가질 수 있으며, 새롭게 만드는 것도 좋습니다. 이 페이지들은 지역화 팀 페이지의 하위 페이지로 생성되어야 합니다.
MDN이 아닌 다른 사이트를 위해 쓰여진 콘텐츠를 적용하는 스타일 표준에 대한 내용은 One Mozilla 스타일 가이드를 참고하세요.
아무리 방대한 문서화 스타일 가이드라도 가장 기본적인 텍스트 표준에서 시작하는 것이 좋습니다. 텍스트 표준은 일관된 문서화를 유지하는데 도움을 줍니다. 이어지는 섹션에서 도움이 될 만한 이런 기본들을 설명합니다.
페이지 제목은 검색 결과에 사용되며, 페이지 상단의 페이지 이동 경로(breadcrumb) 목록에 페이지 계층 구조를 구성하는 데 사용됩니다. (페이지 상단과 검색 결과 상단에 표시되는) 페이지 제목은 페이지 "슬러그"와 다를 수 있습니다. "슬러그"는 페이지 URL의 일부로 "<locale>/docs/" 다음에 따라오는 부분입니다.
페이지 타이틀과 섹션 제목은 헤드라인 스타일 대문자넣기보다는 (첫번째 단어와 필요한 명사만 대문자를 넣는 방식의)일반 문장 스타일 대문자넣기를 해야 합니다:
이런 스타일 규칙이 적용되기 전에 작성된 수많은 예전 문서들이 현재도 존재합니다. 자유롭게 해당 문서들을 수정해도 좋습니다. 우리는 점차적으로 스타일 규칙을 맞춰 나갈겁니다.
페이지 슬러그는 짧게 만들어야 합니다. 새로운 레벨의 계층을 만들때, 그 레벨의 요소는 슬러그에서 한,두 단어로 표현되어야 합니다.
반면에, 페이지 제목은 ,합리적인 범위내에서, 당신이 원하는 만큼 길어도 됩니다. 그리고 구체적이어야 합니다.
어떤 토픽이나 주제 영역에 대한 문서를 추가할 필요가 있다면, 당신이 선택할 일반적인 방법은 랜딩 페이지를 생성한 이후, 각각의 개별적인 문서의 서브페이지를 추가하는 것입니다. 랜딩 페이지는 토픽이나 기술을 설명하는 한두 개의 문단으로 시작한 이후, 각 페이지의 설명이 달린 서브페이지의 목록을 전달해야합니다. 우리가 개발한 몇가지 매크로로 페이지를 목록에 자동으로 삽입할 수 있습니다.
예를 들면 , 아래와 같이 구성된 자바스크립트 가이드를 생각해봅시다.
문서를 문서구조 최상층에 두는 것은 최대한 피해야 합니다. 이렇게 하면 사이트가 느려지며, 사이트 탐색과 네비게이션을 비효율적으로 만듭니다.
주목할 점: 문서 추가는 페이지 생성 권한이 필요합니다.
When writing any document, it's important to know how much to say. If you ramble on too long, or provide excessive detail, the article becomes tedious to read and nobody will use it. Getting the amount of coverage right is important for several reasons. Among those reasons: to ensure that the reader finds the information they truly need, and to provide enough quality material for search engines to adequately analyze and rank the article.
We'll discuss the former (providing the information the reader may need) here. To learn a little about ensuring that pages are properly classified and ranked by search engines, see the article How to write for SEO on MDN.
The goal is to write pages that include all the information that readers may need without going on too long about it all. We have a few recommendations in this area.
Keep in mind that these are guidelines. Some of these tips may not apply in every case. Certainly keep your article's audience in mind. An article on advanced network techniques likely doesn't need to go into as much detail about basic networking concepts as the typical article on networking code, for instance.
Make sure the article's summary—that is, the opening paragraph or paragraphs before the first heading—provides enough information for the reader to understand if the article is likely to be covering what they're interested in reading about.
In guide or tutorial content, the summary should let the reader know what topics will be covered and what they're already expected to know, if anything. It should mention the technology, technologies, and/or APIs that are being documented or discussed, with links to those, and it should offer hints as to the situations in which the article's contents might be useful.
This example of a summary is far too short. It leaves out too much information, such as what it means exactly to "stroke" text, where the text is drawn, and so forth.
CanvasRenderingContext2D.strokeText() draws a string.Here, we've updated the summary, but now it's far too long. Too much detail is included, and the text gets far too much into other methods and properties.
Instead, the summary should focus on the strokeText() method, and should refer to the appropriate guide where the other details are offered.
When called, the Canvas 2D API method CanvasRenderingContext2D.strokeText() strokes the characters in the specified string beginning at the coordinates specified, using the current pen color.In the terminology of computer graphics, "stroking" text means to draw the outlines of the glyphs in the string without filling in the contents of each character with color.
The text is drawn using the context's current font as specified in the context's {{domxref("CanvasRenderingContext2D.font", "font")}} property.
The placement of the text relative to the specified coordinates are determined by the context's textAlign, textBaseline, and direction properties. textAlign controls the placement of the string relative to the X coordinate specified; if the value is "center", then the string is drawn starting at x - (stringWidth / 2), placing the specified X-coordinate in the middle of the string. If the value is "left", the string is drawn starting at the specified value of x. And if textAlign is "right", the text is drawn such that it ends at the specified X-coordinate.
(etc etc etc...)
You can, optionally, provide a fourth parameter that lets you specify a maximum width for the string, in pixels. If you provide this parameter, the text is compressed horizontally or scaled (or otherwise adjusted) to fit inside a space that wide when being drawn.
You can call the fillText() method to draw a string's characters as filled with color instead of only drawing the outlines of the characters.
Here we see a much better overview for the strokeText() method.
The {{domxref("CanvasRenderingContext2D")}} method strokeText(), part of the Canvas 2D API, strokes—that is, draws the outlines of—the characters of a specified string, anchored at the position indicated by the given X and Y coordinates. The text is drawn using the context's current {{domxref("CanvasRenderingContext2D.font", "font")}}, and is justified and aligned according to the {{domxref("CanvasRenderingContext2D.textAlign", "textAlign")}}, {{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline")}}, and {{domxref("CanvasRenderingContext2D.direction", "direction")}} properties.
For more details and further examples, see {{SectionOnPage("/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Text")}} in the Learning Area as well as our main article on the subject, Drawing text.
More pages should have examples than not. The majority of pages probably deserve multiple examples, in fact.
It's important to ensure that you use examples to clarify what every parameter is used for, and to clarify any edge cases that may exist. You should also use examples to demonstrate solutions for common tasks, and you should use examples to demonstrate solutions to problems that may arise.
Each example should be preceded by text explaining what the example does and anything the reader should know before beginning to read or try out the example.
Each piece of code should include an explanation of how it works. Keep in mind that it may make sense to break up a large piece of code into smaller portions so they can be described individually.
The text following each piece of code should explain anything relevant, using an appropriate level of detail.
When using the live sample system, it's helpful to be aware that all of the {{HTMLElement("pre")}} blocks in the area that contains the sample are concatenated together before running the example, which lets you break any or all of the HTML, CSS, and JavaScript into multiple segments, each optionally with its own descriptions, headings, and so forth. This makes documenting code incredibly powerful and flexible.
If an article is "thin"—that is, too short—it may not be indexed properly (or at all) by search engines. As a rule of thumb, the article's body text should be at least 250–300 words. Don't artificially inflate a page, but treat this guideline as a minimum target length when possible.
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, consider breaking up the article into several smaller articles with a landing page, and linking them together using the following macros: {{TemplateLink("Next")}}, {{TemplateLink("Previous")}}, and {{TemplateLink("PreviousNext")}}.
SuperAmazingThing interface". It should instead just be "Using the SuperAmazingThing interface".The Enter (or Return) key on your keyboard starts a new paragraph. To insert a newline, rather than a new paragraph (that is, to create a {{HTMLElement("br")}} instead of a {{HTMLElement("p")}}), hold down the Shift key while pressing Enter.
Lists should be formatted and structured uniformly across all contributions. Individual list items should be written with suitable punctuation, regardless of the list format. However, depending on the type of list you are creating, you will want to adjust your writing as described in the sections below.
Bulleted lists should be used to group related pieces of concise information. Each item in the list should follow a similar sentence structure. Phrases and sentences in bulleted lists should include standard punctuation. Periods must appear at the end of each sentence in a bulleted list, including the item's final sentence, just as would be expected in a paragraph.
An example of a correctly structured bulleted list:
In this example we should include:
Note how the same sentence structure repeats from bullet to bullet. In this example, each bullet point states a condition followed by a comma and a brief explanation, and each item in the list ends with a period.
Numbered lists are used primarily to enumerate steps in a set of instructions. Because instructions can be complex, clarity is a priority, especially if the text in each list item is lengthy. As with bulleted lists, follow standard punctuation usage.
An example of a correctly structured numbered list:
In order to correctly structure a numbered list, you should:
This is an example of writing a closing explanation. We have created a short numbered list that provides instructive steps to produce a numbered list with the correct formatting.
Note how the items in numbered lists read like short paragraphs. Because numbered lists are routinely used for instructional purposes, or to walk someone through an orderly procedure, be sure to keep each item focused: one item per number or step.
Use the "Formatting Styles" drop-down list to apply predefined styles to selected content.
The "Note Box" style is used to call out important notes, like this one.
Similarly, the "Warning Box" 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, ask for help in the MDN discussion forum.
Note: This section deals with the styling/formatting of code as it appears on an MDN article. If you want guidelines on actually writing code examples, see our Code sample guidelines.
Use two spaces per tab in all code examples. Indent the code 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);
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(). The parentheses help differentiate methods from other code terms.
Entire lines (or multiple lines) of code should be formatted using syntax highlighting rather than the {{HTMLElement("code")}} element. Select the appropriate language from the language list button (the one with the two code blocks), as seen in the screenshot to the right. This will insert a preformatted code box with line numbers and syntax highlighting for the chosen language.
Note: Do not use the {{HTMLElement("code")}} element inside the {{HTMLElement("pre")}} block!
While this structure is used on some sites, we do not do so on MDN; nesting these elements will break certain aspects of our styling.
The following example shows text with JavaScript formatting:
for (let i = 0, j = 9; i <= 9; i++, j--)
document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);
If no appropriate language is available, use ("No Highlight" in the language menu). This will result in code without syntax highlighting:
x = 42;
When writing the syntax description section of a reference page, use the "Syntax Box" option in the "Styles" drop-down menu in the editor toolbar. This creates a specially-formatted box used specifically for syntax definitions, distinguishing them from other code blocks.
There are a few use cases where a <pre> block does not refer to code and doesn't have syntax highlighting nor line numbers. In such cases you should add a <pre> without a class attribute. Those cases include things like tree structures:
root/
folder1/
file1
folder2/
file2
file3
To create preformatted content without syntax highlighting and line numbers click the "pre" button in the toolbar. Then start to type the text.
There are specific rules to follow when writing about HTML elements. These rules produce consistent descriptions of elements and their components. They also ensure correct linking to detailed documentation.
<title>).code font. Additionally, put them in bold face when the attribute is mentioned in association with an explanation of what it does, or the first time it's used in the article.<code> to attribute values, and don't use quotation marks around string values, unless needed by the syntax of a code sample.type attribute of an <input> element is set to email or tel ..."| 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 |
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.
Also, 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.
Use full capitals and delete periods in all acronyms and abbreviations, including organizations such as "US" and "UN".
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.
For plurals of acronyms or abbreviations, add s. Don't use an apostrophe. Ever. Please.
The contraction "vs." is preferred.
Use standard English capitalization rules in body text, and capitalize "World Wide Web." It is acceptable to use lower case for "web" (used alone or as a modifier) and "internet".
This guideline is a change from a previous version of this guide, so you may find many instances of "Web" and "Internet" on MDN.
Feel free to change these as you are making other changes, but editing an article just to change capitalization is not necessary.
Keyboard keys should use sentence-style capitalization, not all-caps capitalization. For example, "Enter" not "ENTER." The only exception is that if you wish to abbreviate the name of the "Escape" key, you may use "ESC".
Certain words should always be capitalized (such as trademarks which include capital letters), or words derived from the name of a person (unless it's being used within code, and the rules of the language in which the code is written mandate lower-casing). Some examples:
Our writing style tends to be casual, so you should feel free to use contractions (e.g., "don't", "can't", "shouldn't"), if you prefer.
Use English-style plurals, not the Latin- or Greek-influenced forms.
Hyphenate compounds when the last letter of the prefix is a vowel and is the same as the first letter of the root.
It is a good idea to use gender-neutral language in any 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" is fine; but if the subject is a person of either gender, "he"/"his" isn't 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 are gender-specific. To fix this, use gender-neutral pronouns:
A confirmation dialog appears, asking the user if they allow the Web page to make use of their Web cam.
MDN allows the use of this very common syntax (which is controversial among usage authorities) to make up for the lack of a neutral gender in English.
The use of the third-person plural as a gender neutral pronoun (that is, using "they," "them", "their," and "theirs") is an accepted practice, commonly known as "singular 'they.'"
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:
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. 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 different gender rules. This solution can make translation easier for both readers and localizers.
For dates (not including dates in code samples) use the format "January 1, 1990".
Alternately, you can use the YYYY/MM/DD format.
For decades, use the format "1990s". Don't use an apostrophe.
For plurals of numerals add "s". Don't use an apostrophe.
In running text, use commas only in five-digit and larger numbers.
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.
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.
Do not use "curly" quotes and quotation marks. On MDN, we only use straight quotes and apostrophes.
There are a couple of reasons for this.
For words with variant spellings, always use their American English spelling.
In general, use the first entry at Dictionary.com, unless that entry is listed as a variant spelling or as being primarily used in a non-American form of English. For example, if you look up "behaviour", you find the phrase "Chiefly British" followed by a link to the American standard form, "behavior". Do not use variant spellings.
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.
When you reference a given element for the first time in a section, you 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).
The preferred term on MDN is parameters. Please avoid the term "arguments" for consistency whenever possible.
In task sequences, describe user interface actions using the imperative mood. Identify the user interface element by its label and type.
While the active voice is preferred, the passive voice is also acceptable, given the informal feel of our content. Try to be consistent, though.
링크는 위키를 강력한 배움과 가르침의 도구로 만드는 데 큰 역할을 합니다. 아래에서 관련한 기본적 정보를 찾을 수 있지만, 에디터 가이드에 있는 MDN에서 링크를 생성하고 편집하기 에서는 완전한 가이드를 볼 수 있습니다.
우리는 당신이 문서간에 적절한 링크를 생성하도록 권장합니다; 링크는 콘덴츠 검색 용이성및 네비게이션을 개선하는데 도움을 주고, 구글과 같은 검색 엔진이 더 나은 검색결과를 제공하도록 중요한 콘텍스트를 제공 합니다. 모든 페이지는 단어나 구문에서 관련된 주제의 다른 페이지로 연결되는 좋은 링크집합을 가져야 합니다. 링크는 용어를 정의하거나 어떤 주제에 대한 상세하고 심화된 문서를 제공하는데에 모두 사용될 뿐만 아니라, 관련된 예제나 보다 관심이 갈만한 정보도 제공할 수도 있습니다.
MDN내부의 문서(내부 링크)뿐만아니라 MDN 외부의 페이지(외부 링크)도 쉽게 링크를 걸 수 있습니다 .
링크를 만드는 두 가지 방법이 있습니다:
어떤 텍스트에 링크를 연결할 것인지에 대해, 몇가지 가이드라인을 소개합니다:
보안 때문에, 아래 스킴(schemes)을 사용한 링크만 생성할 수 있다:
http://https://ftp://mailto:이 외의 것은 동작할 수도 아닐수도 있지만, 편집 스태프에 의해 지원되거나 삭제되지 않을 것이다.
특별히, about: 이나 chrome:// 스킴은 동작하지 않으므로 피해야 한다.
유사하게 , javascript: 스킴도 jar:와 마찬가지로 대부분의 모던 브라우저에서 막혀있다
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, just click the little "×" 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:
Use for content that is technically superseded, but still valid in context. For example, this might be an HTML element that is obsolete in HTML5, but still valid in HTML 4.01.
You can also use the {{TemplateLink("obsolete_header")}} macro to put a prominent banner on the topic.
Use for content that is technically superseded 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.
The SEO summary provides a short description of a 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. (In other words, it's not just for SEO.)
By default, the first paragraph 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:
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 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 (e.g., "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 column should contain one or more of the following sections, in order:
{{TODO("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:
svgo tool to optimize the SVG file before sending it. The default configuration is fine.Important: Remember to save any changes you've made before uploading an attachment to your article! The editor is closed during the upload process, and currently does not verify whether or not you wish to save your work when it does so.
If you have questions about usage and style not covered here, we recommend referring to the Microsoft Writing Style Guide—or, failing that, the Chicago Manual of Style. An unofficial crib sheet for the Chicago Manual of Style is available online.
For questions of spelling, please refer to Dictionary.com. The spelling checker for this site uses American English. Please do not use variant spellings (e.g., use color rather than colour).
We will be expanding the guide over time, so if you have specific questions that aren't covered in this document, please post them on the MDN discussion forum, so we know what should be added.
If you're interested in improving your writing and editing skills, you may find the following resources to be helpful.
