MDN Style Guide

  • Revision slug: Project:MDC_style_guide
  • Revision title: MDN Style Guide
  • Revision id: 323613
  • Created:
  • Creator: ethertank
  • Is current revision? No
  • Comment

Revision Content

Content on this page has been moved to the style guide. This page will be deprecated with a redirect.

{{MDCProjectPagesTOC}}

Page naming for the MDC Wiki is relatively straightforward, but it's important you get it correct in order to take full advantage of the breadcrumb list at the top of the page.

Please also refer to the Writer's guidelines when choosing a page name.

General conventions

Capitalization

Page names should use sentence style capitalization (only capitalize the first word and any proper nouns) rather than headline style capitalization:

  • Correct: "A new method for creating JavaScript rollovers"
  • Incorrect: "A New Method for Creating JavaScript Rollovers"
For the time being these capitalization rules for page names apply only to new pages. There are a large number of pages in our wiki that do not conform to these rules, but please do not correct those at this time. We will sort out the logistics and fix older page names at some point in the future. Thanks. -- dria 09:20, 14 March 2006 (PST)

One-page articles

Content with a unique title

If you are adding an article or other content that only requires a single page in the wiki, simply use the name of that article as the page name.

For example, the page for a one-page article called "A new approach to JavaScript rollovers" would be, simply A new approach to JavaScript rollovers. So long as your content title is unique, this is the easiest and preferred approach.

Content with a non-unique title

Wherever possible, you should try to create content with unique titles, in order to simplify the page naming as much as possible. If this is impossible, prefix the title with the topic, followed by a slash and no spaces.

For example, if I needed to add a page called "Optimization", simply calling the page "Optimization" would create a possible conflict as Optimization can apply to a wide variety of topics within the wiki. If my Optimization article was specifically about CSS, I would expand my title so it is unique (ie: CSS optimization).

If there are two or more pages which have the same "natural" title, a disambiguation page should be created.

It is a best-practice within this wiki to have unique article titles wherever possible.

Multiple-page content

If the content you are adding to the wiki requires multiple pages, use the following page naming method. This allows MindTouch Deki to build the breadcrumbs list at the top of the page correctly.

If you don't use the pathname-like hierarchy depicted here, your articles will all be located at the top of the hierarchy, instead of nested.

Revision Source

<div class="note">
  <p>Content on this page has been moved to the <a href="/en-US/docs/Project:MDC_style_guide" title="Project:MDC_style_guide">style guide</a>. This page will be deprecated with a redirect.</p>
</div>
<div>
  {{MDCProjectPagesTOC}}</div>
<p>Page naming for the MDC Wiki is relatively straightforward, but it's important you get it correct in order to take full advantage of the breadcrumb list at the top of the page.</p>
<p>Please also refer to the <a href="/en-US/docs/Project:Writer's_guide" title="Project:Writer's_guide">Writer's guidelines</a> when choosing a page name.</p>
<h2 id="General_conventions">General conventions</h2>
<h3 id="Capitalization">Capitalization</h3>
<p>Page names should use sentence style capitalization (only capitalize the first word and any proper nouns) rather than headline style capitalization:</p>
<ul>
  <li><strong>Correct</strong>: "A new method for creating JavaScript rollovers"</li>
  <li><strong>Incorrect</strong>: "A New Method for Creating JavaScript Rollovers"</li>
</ul>
<div class="note">
  For the time being these capitalization rules for page names apply only to new pages. There are a large number of pages in our wiki that do not conform to these rules, but please do not correct those at this time. We will sort out the logistics and fix older page names at some point in the future. Thanks. -- <a href="/User:Dria" title="User:Dria">dria</a> 09:20, 14 March 2006 (PST)</div>
<h2 id="One-page_articles">One-page articles</h2>
<h3 id="Content_with_a_unique_title">Content with a unique title</h3>
<p>If you are adding an article or other content that only requires a single page in the wiki, simply use the name of that article as the page name.</p>
<p>For example, the page for a one-page article called "A new approach to JavaScript rollovers" would be, simply <a href="/en-US/docs/A_new_approach_to_JavaScript_rollovers" title="A_new_approach_to_JavaScript_rollovers">A new approach to JavaScript rollovers</a>. So long as your content title is unique, this is the easiest and preferred approach.</p>
<h3 id="Content_with_a_non-unique_title">Content with a non-unique title</h3>
<p>Wherever possible, you should try to create content with unique titles, in order to simplify the page naming as much as possible. If this is impossible, prefix the title with the topic, followed by a slash and no spaces.</p>
<p>For example, if I needed to add a page called "Optimization", simply calling the page "Optimization" would create a possible conflict as Optimization can apply to a wide variety of topics within the wiki. If my Optimization article was specifically about CSS, I would expand my title so it is unique (ie: <a href="/en-US/docs/CSS_optimization" title="CSS_optimization">CSS optimization</a>).</p>
<p>If there are two or more pages which have the same "natural" title, a <a href="/en-US/docs/Project:Disambiguation" title="Project:Disambiguation">disambiguation page</a> should be created.</p>
<p><strong>It is a best-practice within this wiki to have unique article titles wherever possible.</strong></p>
<h2 id="Multiple-page_content">Multiple-page content</h2>
<p>If the content you are adding to the wiki requires multiple pages, use the following page naming method. This allows MindTouch Deki to build the breadcrumbs list at the top of the page correctly.</p>
<ul>
  <li><a href="/en-US/learn/javascript" title="Learning_JavaScript">Learning JavaScript</a> - Main table-of-contents page</li>
  <li>{{todo}}<a href="/en-US/learn/Learning_JavaScript/Introduction" title="Learning_JavaScript/Introduction">Learning JavaScript/Introduction</a></li>
  <li>{{todo}}<a href="/en-US/learn/Learning_JavaScript/A_layperson's_view" title="Learning_JavaScript/A_layperson's_view">Learning JavaScript/A layperson's view</a></li>
  <li>{{todo}}<a href="/en-US/learn/Learning_JavaScript/More_advanced_scripting" title="Learning_JavaScript/More_advanced_scripting">Learning JavaScript/More advanced scripting</a></li>
  <li>{{todo}}<a href="/en-US/learn/Learning_JavaScript/Next_steps" title="Learning_JavaScript/Next_steps">Learning JavaScript/Next steps</a></li>
</ul>
<p><strong>If you don't use the pathname-like hierarchy depicted here, your articles will all be located at the top of the hierarchy, instead of nested.</strong></p>
Revert to this revision