The MDN editing interface

  • Revision slug: Project:MDC_editor_guide
  • Revision title: The MDN editing interface
  • Revision id: 332399
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment

Revision Content

The WYSIWYG (what-you-see-is-what-you-get) editor offered by MDC makes it easy to contribute new content to the MDN Documentation Center.  This article provides some information on how to use the editor, as well as some information about helpful features that may improve your productivity.

The MDC style guide offers information about how to format and style the content itself.

Keyboard shortcuts

There are a number of convenient keyboard shortcuts available to help you avoid taking your hands off the keyboard while you work.  The shortcuts are listed for Windows and Linux; on Mac, instead of using the Control key, you can use the Command key.

Shortcut Description
Ctrl-A Select all
Ctrl-C Copy to clipboard
Ctrl-V Paste from clipboard
Ctrl-X Cut
Ctrl-Z Undo
Ctrl-Y Redo
Ctrl-K Open link editor
Ctrl-B Bold
Ctrl-I Italic
Ctrl-O Toggle <code> style.
Ctrl-Shift-O Toggle source view mode.
Ctrl-P Toggles the <pre> style on the current block.
Ctrl-U Underline
Ctrl-S Save changes and close the editor
Ctrl-Shift-S Save changes without closing the editor
Ctrl-2 through Ctrl-6 Select header level 2-6
Ctrl-Shift-L Toggles between bulleted list, numbered list, and paragraph format
Tab Increases indent level if in indent mode, otherwise inserts two spaces as a tab.  Inside tables, this jumps to the next cell, or inserts a new row if there is no next cell.  If the cursor is currently in the page title or in a header, the cursor jumps to the next paragraph.
Shift-Tab Decreases indent level if in indent mode.  Inside tables, this jumps to the previous cell, or inserts a new row if there is no previous cell.  If the cursor is currently in the page title or in a header, the cursor jumps to the next paragraph.
Shift-Space Inserts a non-breaking space (&nbsp;)
Shift-Enter

Exits out of the current block.  For example, if you're currently editing a <pre> block, shift-Enter exits the block, putting you back in the body of the article.

Note: Not currently implemented; see {{bug(780055)}}.

Including a revision note

When saving your change, it's helpful if you include a note explaining why you made the change. Enter some text in the "Edit summary" box below the editor before saving your change.

There are a few reasons this is helpful:

  • If the reason for your change isn't obvious, your note can explain the reasoning to others.
  • If your change is technically complex, it can explain to editors the logic behind it; this can include a bug number, for example, that editors can refer to for more information.
  • If your edit involves deleting a large amount of content, you can justify the deletion (for example, "I moved this content to article X").

Linking

There are some templates that make it easy to create in-page links. For example, you can link to a section with a given name using the anch template, like this:

{{anch("Including a revision note")}}

This inserts an anchor like this: {{ anch("Including a revision note") }}.

When writing interface documentation, and you need to link to a method within the current article, you can use the manch template, like this:

{{manch("methodName")}}

This looks like this: {{ manch("methodName") }}.

Using live sample code

Note: The live sample system is still undergoing heavy development, and it may or may not work correctly at any given time. Expect changes to make it easier to use that may make this documentation obsolete before we get it updated. We'll try to keep this information up-to-date though!

The MDN wiki supports live code samples. These samples use HTML, and may also have CSS and/or JavaScript. To use the live sample system, click the "Insert Code Sample Template" button, located in the second row of the toolbar. It looks like this: What the live sample button in the toolbar looks like

Clicking that button asks for a title for your sample, then adds several things to your article: a heading and three <pre> blocks. One of these blocks is for your sample's HTML, one is for its CSS, and one is for its JavaScript. Each has its own subheading, to make it extra clear which is which. You can remove the CSS and/or JavaScript blocks, or the headings, if you don't need them.

Note: In fact, your sample doesn't even need to have a heading at all. If it's in a {{HTMLElement("div")}} or other block, you can use that block's ID too.

Fill out each of the code blocks as appropriate, removing any your sample doesn't need. You can even add more code blocks; the sample system automatically concatenates all the HTML, CSS, and JavaScript code snippets in the section together and uses them all together. So you can describe how your example works a piece at a time, and it should still work!

Once you've created your code, you can add an {{HTMLElement("iframe")}} that displays it by using the EmbedLiveSample template, like this:

\{{EmbedLiveSample("section_id")}}

It's important to note that the "section_id" is not necessarily the same as the heading of your code sample's section. For example, non-ASCII characters get encoded, and all spaces are replaced with underscores. And if the heading name isn't unique in your article, it's ID will be adjusted to be unique. So while you can try just entering your section name with underscores replacing spaces, you may need to save your article so that the server generates the ID, then re-edit the article to update the ID in the template call. You can determine what the ID is by looking at the part of the URL after the "#" character in the page's table of contents.

You can also, optionally, provide width and height parameters to EmbedLiveSample, which lets you specify the size of the {{HTMLElement("iframe")}}:

\{{EmbedLiveSample("section_id", 600, 100)}}

This creates an {{HTMLElement("iframe")}} that's 600 pixels wide and 100 pixels tall. You must specify both the width and the height; if you only include one, the default frame size is used.

Note: It's also useful to note that in many cases, you should be able to add the EmbedLiveSample template call to existing articles with code snippets and make them work without significant (if any) extra work. As long as the example is in a section of its own, or can easily be put into one, just add the template and you're good to go!

Deleting a page

If you come upon a page that needs to be deleted for any reason, simply add the tag "junk" to it. A helpful MDC administrator will remove the page shortly thereafter.

What are good reasons to mark a page for deletion?

  • The page was created by accident and has no content.
  • The page's contents were merged with another article.
  • The page is spam.
  • The page's contents are so woefully obsolete as to be dangerous.

Useful KumaScript commands

Sometimes, it's useful to take advantage of special DekiScript commands to improve the look and feel of your content.

By default, the MindTouch wiki truncates lengthy URLs when displaying them in the bodies of articles. This is not typically what we want. If you find this is happening to you, you can use the web.link command to embed the full URL, like this:

Truncated: http://www.bitstampede.com/2009/06/0...atures-on-mdc/

Inlined: {{ web.link("http://www.bitstampede.com/2009/06/04/more-new-features-on-mdc/") }}

This is done by using the text {{web.link("http://www.bitstampede.com/2009/06/04/more-new-features-on-mdc/")}}.

Using syntax highlighting

MDC supports syntax highlighting for code samples.  To use it, the first step is to insert the code sample into the document:

void main(int argc, char **argv) {

printf("Hello world\n");

}

The second step is to select the text and click the "PRE" icon in the toolbar.

void main(int argc, char **argv) {
  printf("Hello world\n");
}

The third step is to use the drop-down menu next to the "PRE" icon to select the language corresponding to the syntax highlighting you wish to apply.  In this case, we'll use the C++ syntax highlighter.

void main(int argc, char **argv) {
  printf("Hello world\n");
}
Note: The editor does not display the syntax highlighting.  You'll need to save your changes and look at the article to see the syntax highlighting in effect.

Accessing your browser's standard contextual menu

By default, the editor uses its own contextual menu when you right-click on the editor. To access your browser's default contextual menu (such as to access the Firefox spell checker's list of suggested corrections), hold down the Control key (the Command key on Mac OS X) while clicking.

The toolbar

Some key features of the editor toolbar are covered here. For more information, you may wish to check out the CKeditor user's guide; this is the editor MDC uses.

The underlying content for all articles is HTML; you may at any time view and edit the HTML source for any article by clicking the "Source" button in the toolbar.

The style dropdown menu, located in the bottom row of the toolbar, lists a number of commonly used styles you can apply to text:

  • "Code (inline)" is used for short code snippets, function names, class names, interface names, and so forth.
  • "Plaintext (nowiki)" lets you flag a region of content, indicating it should not be processed by the wiki. For example, this will prevent URLs in the middle of code samples from being turned into clickable links.
  • "Note" is used for paragraphs that include important information to be specially called out. You should start a note paragraph with "Note:" in bold.
  • "Warning" is used for critical messages; typically these should start with "Warning:" in bold.
  • "Callout box" is the style used for callout boxes; this is used in tandem with templates such as Template:gecko_callout_heading.
  • "Two columns" and "Three columns" should be self-explanatory.

Redirects

If you need to make a page redirect to another page, you can use the REDIRECT command. To do this, simply make the entire content of your article look like this:

REDIRECT <a class="redirect" href="%(location)s">%(title)s</a>

Once you've done this, any visit to the page will automatically redirect to the specified location.

If you need to view a page that performs a redirect at a later time, simply add "?redirect=no" to its URL. This will prevent the redirect from occurring so you can view and edit the redirect command.

See also

{{ languages( {"ja": "Project:ja/MDC editor guide"} ) }}

Revision Source

<p>The WYSIWYG (what-you-see-is-what-you-get) editor offered by MDC makes it easy to contribute new content to the MDN Documentation Center.&nbsp; This article provides some information on how to use the editor, as well as some information about helpful features that may improve your productivity.</p>
<p>The <a href="/Project:En/MDC_style_guide" title="Project:En/MDC style guide">MDC&nbsp;style guide</a> offers information about how to format and style the content itself.</p>
<h2 id="Keyboard_shortcuts">Keyboard shortcuts</h2>
<p>There are a number of convenient keyboard shortcuts available to help you avoid taking your hands off the keyboard while you work.&nbsp; The shortcuts are listed for Windows and Linux; on Mac, instead of using the Control key, you can use the Command key.</p>
<table class="standard-table" style="max-width:45em" summary="Keyboard shortcuts in the MDC editor.">
  <tbody>
    <tr>
      <th>Shortcut</th>
      <th>Description</th>
    </tr>
    <tr>
      <td>Ctrl-A</td>
      <td>Select all</td>
    </tr>
    <tr>
      <td>Ctrl-C</td>
      <td>Copy to clipboard</td>
    </tr>
    <tr>
      <td>Ctrl-V</td>
      <td>Paste from clipboard</td>
    </tr>
    <tr>
      <td>Ctrl-X</td>
      <td>Cut</td>
    </tr>
    <tr>
      <td>Ctrl-Z</td>
      <td>Undo</td>
    </tr>
    <tr>
      <td>Ctrl-Y</td>
      <td>Redo</td>
    </tr>
    <tr>
      <td>Ctrl-K</td>
      <td>Open link editor</td>
    </tr>
    <tr>
      <td>Ctrl-B</td>
      <td>Bold</td>
    </tr>
    <tr>
      <td>Ctrl-I</td>
      <td>Italic</td>
    </tr>
    <tr>
      <td>Ctrl-O</td>
      <td>Toggle <code>&lt;code&gt;</code> style.</td>
    </tr>
    <tr>
      <td>Ctrl-Shift-O</td>
      <td>Toggle source view mode.</td>
    </tr>
    <tr>
      <td>Ctrl-P</td>
      <td>Toggles the <code>&lt;pre&gt;</code> style on the current block.</td>
    </tr>
    <tr>
      <td>Ctrl-U</td>
      <td>Underline</td>
    </tr>
    <tr>
      <td>Ctrl-S</td>
      <td>Save changes and close the editor</td>
    </tr>
    <tr>
      <td>Ctrl-Shift-S</td>
      <td>Save changes without closing the editor</td>
    </tr>
    <tr>
      <td>Ctrl-2 through Ctrl-6</td>
      <td>Select header level 2-6</td>
    </tr>
    <tr>
      <td>Ctrl-Shift-L</td>
      <td>Toggles between bulleted list, numbered list, and paragraph format</td>
    </tr>
    <tr>
      <td>Tab</td>
      <td>Increases indent level if in indent mode, otherwise inserts two spaces as a tab.&nbsp; Inside tables, this jumps to the next cell, or inserts a new row if there is no next cell.&nbsp; If the cursor is currently in the page title or in a header, the cursor jumps to the next paragraph.</td>
    </tr>
    <tr>
      <td>Shift-Tab</td>
      <td>Decreases indent level if in indent mode.&nbsp; Inside tables, this jumps to the previous cell, or inserts a new row if there is no previous cell.&nbsp; If the cursor is currently in the page title or in a header, the cursor jumps to the next paragraph.</td>
    </tr>
    <tr>
      <td>Shift-Space</td>
      <td>Inserts a non-breaking space (<code>&amp;nbsp;</code>)</td>
    </tr>
    <tr>
      <td>Shift-Enter</td>
      <td>
        <p>Exits out of the current block. &nbsp;For example, if you're currently editing a<code> &lt;pre&gt; </code>block, shift-Enter exits the block, putting you back in the body of the article.</p>
        <div class="note style-wrap">
          <p><strong>Note:</strong> Not currently implemented; see {{bug(780055)}}.</p>
        </div>
      </td>
    </tr>
  </tbody>
</table>
<h2 id="Including_a_revision_note">Including a revision note</h2>
<p>When saving your change, it's helpful if you include a note explaining why you made the change. Enter some text in the "Edit summary" box below the editor before saving your change.</p>
<p>There are a few reasons this is helpful:</p>
<ul>
  <li>If the reason for your change isn't obvious, your note can explain the reasoning to others.</li>
  <li>If your change is technically complex, it can explain to editors the logic behind it; this can include a bug number, for example, that editors can refer to for more information.</li>
  <li>If your edit involves deleting a large amount of content, you can justify the deletion (for example, "I moved this content to article X").</li>
</ul>
<h2 id="Linking">Linking</h2>
<p>There are some templates that make it easy to create in-page links. For example, you can link to a section with a given name using the <a href="/Template:anch" title="Template:anch">anch</a> template, like this:</p>
<p><span class="nowiki">{{anch("Including a revision note")}}</span></p>
<p>This inserts an anchor like this:&nbsp;{{ anch("Including a revision note") }}.</p>
<p>When writing interface documentation, and you need to link to a method within the current article, you can use the <a href="/Template:manch" title="Template:manch">manch</a> template, like this:</p>
<p><span class="nowiki">{{manch("methodName")}}</span></p>
<p>This looks like this:&nbsp;{{ manch("methodName") }}.</p>
<h2 id="Using_live_sample_code">Using live sample code</h2>
<div class="note">
  <p><strong>Note:</strong> The live sample system is still undergoing heavy development, and it may or may not work correctly at any given time. Expect changes to make it easier to use that may make this documentation obsolete before we get it updated. We'll try to keep this information up-to-date though!</p>
</div>
<p>The MDN wiki supports live code samples. These samples use HTML, and may also have CSS and/or JavaScript. To use the live sample system, click the "Insert Code Sample Template" button, located in the second row of the toolbar. It looks like this: <img alt="What the live sample button in the toolbar looks like" src="/files/4265/live-sample-button.png" style="width: 21px; height: 19px;" /></p>
<p>Clicking that button asks for a title for your sample, then adds several things to your article: a heading and three <span style="font-family: courier new,courier;">&lt;pre&gt;</span> blocks. One of these blocks is for your sample's HTML, one is for its CSS, and one is for its JavaScript. Each has its own subheading, to make it extra clear which is which. You can remove the CSS and/or JavaScript blocks, or the headings, if you don't need them.</p>
<div class="note">
  <p><strong>Note: </strong>In fact, your sample doesn't even need to have a heading at all. If it's in a {{HTMLElement("div")}} or other block, you can use that block's ID too.</p>
</div>
<p>Fill out each of the code blocks as appropriate, removing any your sample doesn't need. You can even add more code blocks; the sample system automatically concatenates all the HTML, CSS, and JavaScript code snippets in the section together and uses them all together. So you can describe how your example works a piece at a time, and it should still work!</p>
<p>Once you've created your code, you can add an {{HTMLElement("iframe")}} that displays it by using the <a href="/en-US/docs/Template:EmbedLiveSample" title="/en-US/docs/Template:EmbedLiveSample">EmbedLiveSample</a> template, like this:</p>
<pre>
\{{EmbedLiveSample("section_id")}}</pre>
<p>It's important to note that the "section_id" is not necessarily the same as the heading of your code sample's section. For example, non-ASCII characters get encoded, and all spaces are replaced with underscores. And if the heading name isn't unique in your article, it's ID will be adjusted to be unique. So while you can try just entering your section name with underscores replacing spaces, you may need to save your article so that the server generates the ID, then re-edit the article to update the ID in the template call. You can determine what the ID is by looking at the part of the URL after the "#" character in the page's table of contents.</p>
<p>You can also, optionally, provide width and height parameters to <a href="/en-US/docs/Template:EmbedLiveSample" title="/en-US/docs/Template:EmbedLiveSample">EmbedLiveSample</a>, which lets you specify the size of the {{HTMLElement("iframe")}}:</p>
<pre>
\{{EmbedLiveSample("section_id", 600, 100)}}</pre>
<p>This creates an {{HTMLElement("iframe")}} that's 600 pixels wide and 100 pixels tall. You must specify both the width and the height; if you only include one, the default frame size is used.</p>
<div class="note">
  <p><strong>Note:</strong> It's also useful to note that in many cases, you should be able to add the EmbedLiveSample template call to existing articles with code snippets and make them work without significant (if any) extra work. As long as the example is in a section of its own, or can easily be put into one, just add the template and you're good to go!</p>
</div>
<h2 id="Deleting_a_page">Deleting a page</h2>
<p>If you come upon a page that needs to be deleted for any reason, simply add the tag "junk"&nbsp;to it. A helpful MDC administrator will remove the page shortly thereafter.</p>
<p>What are good reasons to mark a page for deletion?</p>
<ul>
  <li>The page was created by accident and has no content.</li>
  <li>The page's contents were merged with another article.</li>
  <li>The page is spam.</li>
  <li>The page's contents are so woefully obsolete as to be dangerous.</li>
</ul>
<h2 id="Useful_KumaScript_commands">Useful KumaScript commands</h2>
<p>Sometimes, it's useful to take advantage of special DekiScript commands to improve the look and feel of your content.</p>
<h3 id="Ensuring_that_full_links_are_displayed_inline">Ensuring that full links are displayed inline</h3>
<p>By default, the MindTouch wiki truncates lengthy URLs when displaying them in the bodies of articles. This is not typically what we want. If you find this is happening to you, you can use the <code>web.link</code> command to embed the full URL, like this:</p>
<p>Truncated: <a class="external" href="http://www.bitstampede.com/2009/06/04/more-new-features-on-mdc/" rel="freelink">http://www.bitstampede.com/2009/06/0...atures-on-mdc/</a></p>
<p>Inlined:&nbsp;{{ web.link("http://www.bitstampede.com/2009/06/04/more-new-features-on-mdc/") }}</p>
<p>This is done by using the text <span class="plain"><code><span class="nowiki">{{web.link("http://www.bitstampede.com/2009/06/04/more-new-features-on-mdc/")}}</span></code></span>.</p>
<h2 id="Using_syntax_highlighting">Using syntax highlighting</h2>
<p>MDC supports syntax highlighting for code samples.&nbsp; To use it, the first step is to insert the code sample into the document:</p>
<p>void main(int argc, char **argv) {</p>
<p style="margin-left: 40px;">printf("Hello world\n");</p>
<p>}</p>
<p>The second step is to select the text and click the "PRE" icon in the toolbar.</p>
<pre>
void main(int argc, char **argv) {
&nbsp;&nbsp;printf("Hello world\n");
}
</pre>
<p>The third step is to use the drop-down menu next to the "PRE" icon to select the language corresponding to the syntax highlighting you wish to apply.&nbsp; In this case, we'll use the C++ syntax highlighter.</p>
<pre class="brush: cpp">
void main(int argc, char **argv) {
&nbsp;&nbsp;printf("Hello world\n");
}
</pre>
<div class="note">
  <strong>Note:</strong> The editor does not display the syntax highlighting.&nbsp; You'll need to save your changes and look at the article to see the syntax highlighting in effect.</div>
<div class="noinclude">
  <h2 id="Accessing_your_browser's_standard_contextual_menu">Accessing your browser's standard contextual menu</h2>
  <p>By default, the editor uses its own contextual menu when you right-click on the editor. To access your browser's default contextual menu (such as to access the Firefox spell checker's list of suggested corrections), hold down the Control key (the Command key on Mac OS X) while clicking.</p>
  <h2 id="The_toolbar">The toolbar</h2>
  <p>Some key features of the editor toolbar are covered here. For more information, you may wish to check out the <a class="external" href="http://docs.cksource.com/CKEditor_3.x/Developers_Guide" title="http://docs.cksource.com/CKEditor_3.x/Developers_Guide">CKeditor user's guide</a>; this is the editor MDC uses.</p>
  <p>The underlying content for all articles is HTML; you may at any time view and edit the HTML&nbsp;source for any article by clicking the "Source"&nbsp;button in the toolbar.</p>
  <p>The style dropdown menu, located in the bottom row of the toolbar, lists a number of commonly used styles you can apply to text:</p>
  <ul>
    <li>"Code (inline)" is used for short code snippets, function names, class names, interface names, and so forth.</li>
    <li>"Plaintext (nowiki)" lets you flag a region of content, indicating it should not be processed by the wiki. For example, this will prevent URLs in the middle of code samples from being turned into clickable links.</li>
    <li>"Note"&nbsp;is used for paragraphs that include important information to be specially called out. You should start a note paragraph with "<strong>Note:</strong>" in bold.</li>
    <li>"Warning"&nbsp;is used for critical messages; typically these should start with "<strong>Warning:</strong>"&nbsp;in bold.</li>
    <li>"Callout box" is the style used for callout boxes; this is used in tandem with templates such as <a href="/en-US/docs/Template:gecko_callout_heading" title="/en-US/docs/Template:gecko_callout_heading">Template:gecko_callout_heading</a>.</li>
    <li>"Two columns" and "Three columns" should be self-explanatory.</li>
  </ul>
  <h2 id="Redirects">Redirects</h2>
  <p>If you need to make a page redirect to another page, you can use the <code>REDIRECT</code> command. To do this, simply make the entire content of your article look like this:</p>
  <pre>
<code>REDIRECT &lt;a class="redirect" href="%(location)s"&gt;%(title)s&lt;/a&gt;</code></pre>
  <p>Once you've done this, any visit to the page will automatically redirect to the specified <code><em>location</em></code>.</p>
  <p>If you need to view a page that performs a redirect at a later time, simply add "<code>?redirect=no</code>" to its URL. This will prevent the redirect from occurring so you can view and edit the redirect command.</p>
  <h2 id="See_also">See also</h2>
  <ul>
    <li><a class="internal" href="/Project:en/Using_the_Mozilla_Developer_Center" title="Project:en/Using the Mozilla Developer Center">Using the Mozilla Developer Center</a></li>
    <li><a href="/Project:en/Custom_Templates" title="Project:en/Custom Templates">Custom Templates</a></li>
    <li><a class="external" href="http://docs.fckeditor.net/FCKeditor_2.x/Users_Guide" title="http://docs.fckeditor.net/FCKeditor_2.x/Users_Guide">FCKeditor Users Guide</a></li>
  </ul>
</div>
<div class="noinclude">
  {{ languages( {"ja": "Project:ja/MDC editor guide"} ) }}</div>
Revert to this revision