Source mode

MDN's editor has a prominent button that gives you the ability to switch into source editing mode. In this mode, you see the underlying HTML for the body of the article you're editing. This guide will help you understand what you can do with MDN's wiki content source editing mode, what you should do with it, and, most importantly, what not to do.

Before you consider using source mode, please note that we strongly urge you not to. Unless what you're doing is something you simply have to do in order to meet our style guide (we do have required features that unfortunately can't be created without using source mode yet), you shouldn't need to use source mode. See Warnings and caveats below.

Accessing source mode

Getting into source mode is easy. Perhaps too easy. Click the Source button at the top-left corner of the editor's toolbar, as shown below.

Partial screenshot of the editor toolbar, with the Source mode button highlighted

Due to formatting, images, and the like, it's very possible that the source is so much shorter (vertical length-wise) than the WYSIWYG content that you may need to scroll up quite a lot to find the source within the edit box.

Warnings and caveats

As mentioned previously, you should only rarely need to use source mode. There are a few very specific things you can only do by tweaking the source. Eventually we will update the editing interface to handle those things for you.

Anything that's not expressly described somewhere in the MDN contributor guide should not be added to the source. That means:

  • No custom fonts or styles; if it's not part of our standard look and feel, don't do it.
  • No special colors. Use only the colors that are part of the standard look and feel of MDN, provided by the styles we use.

Working in source mode

Once you're in source mode, you're editing the raw HTML that makes up the content of a wiki page. While you're unconstrained by the editor, you need to do everything you can to make sure your work matches the style guide and that it works safely and reliably.

You should usually only work in source mode for brief tweaks rather than for an extended period of writing time.

Unfortunately, the Tab key doesn't work in our source editor at this time. Please insert two spaces for each place where you would normally use the Tab key.

If you use any HTML elements or attributes that MDN doesn't allow, they will be removed from the HTML when your document is saved. In addition, the document's HTML will be reformatted to keep it moderately readable and consistent.

Legitimate uses for source mode

There are a few specific cases in which the only way to follow MDN's style guide is to resort to the use of source mode. This section covers these cases and how to properly implement these features without breaking other things.

Highlighting lines in sample code

Within the sample code snippet blocks established using the PRE or Syntax Highlighter buttons in the toolbar's block group, you may wish to call special attention to specific lines of code. The only way to do this is to open source mode, find the <pre> block containing the code, and edit the <pre> tag's class attribute to include a highlight component formatted as follows:

  • highlight[lineNum1, lineNum2, ..., lineNumN]

For example, if the existing tag is <pre class="brush: js">, and you want to add highlighting to lines 4 and 7, you would change it to <pre class="brush:js; highlight:[4,7]">.

Let's look at a more complete example:

Before highlighting With highlighting
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");

var path1 = new Path2D();
path1.rect(10, 10, 100, 100);

var path2 = new Path2D(path1);
path2.moveTo(220, 60);
path2.arc(170, 60, 50, 0, 2 * Math.PI);

ctx.stroke(path2);

Here, the <pre> tag is: <pre class="brush: js">

var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");

var path1 = new Path2D();
path1.rect(10, 10, 100, 100);

var path2 = new Path2D(path1);
path2.moveTo(220, 60);
path2.arc(170, 60, 50, 0, 2 * Math.PI);

ctx.stroke(path2);

And here, the <pre> tag has been changed to: <pre class="brush: js; highlight:[4,7]">

Styles that don't have toolbar buttons

We have some styles we use on MDN that are not available using the normal user interface. Fortunately, these aren't used very often. Some examples are:

  • To apply they "keyboard" style, you need to enclose the text of the key's name in the <kbd> element. We have no user interface for this yet. So drop into source mode and wrap the key name in <kbd>. For example, if the source is:
    <p>Press the <kbd>Enter</kbd> key to start the countdown.</p>

    The result is:

    Press the Enter key to start the countdown.

  • Some very uncommon styles used on specialized pages also need to be added by hand. This is especially common with group boxes. That's why we have macros that help to build many of the landing page components automatically.

Document Tags and Contributors

 Contributors to this page: Sheppy, jswisher, sparklust, kscarfone
 Last updated by: Sheppy,