MDN editor basics

Editing content on MDN is easy; you can use the built-in WYSIWYG editor to create, edit, and improve articles and other pages almost anywhere on the site. The editor window, shown below, is comprised of eight key boxes. This section will provide information about each section so you know how to use our entire editing environment.

Page controls

The page controls area offers buttons affecting the page as a whole:

Save and keep editing

Saves the page without closing the editor; this lets you periodically save your work, creating an entry in the page history that you can revert to if you need to, or in case you need to stop working and come back to it later. This option is not available when creating new pages. See The revision comment box to learn how to include a revision comment on your saved article.

Save changes

Saves the page and closes the editor, returning you to view the page in standard browsing mode. See The revision comment box to learn how to include a revision comment on your saved article.

Preview changes

Opens a new tab or window showing the page as it exists in your editor, rendered as if you were browsing to it. This includes executing any macros you use in-content. Your work is not saved when you use this option. This lets you check to be sure you haven't made any errors in your macro syntax or other formatting that may prevent the page from rendering correctly.

Discard changes

Cancels your edit, disposing of any changes you've made without saving them. You're returned to the page in standard browsing mode.

The page info box

The page info box contains information about the page, but also can be expanded to offer additional page controls. By default, it displays the page's title and the date and time at which a local draft was saved; the local draft, stored on your computer, is used as a backup in case you accidentally navigate away from the editor or your browser crashes.

You can click the "Edit Page Title and Properties" link to switch to a view offering additional page controls. This view looks like this:

This view allows you to change the page's display title and the depth of the page's table of contents. The display title is the title shown in the browser's title bar (or tab bar) and as the title of the page at the top of the article and in the breadcrumb bar, as appropriate. It doesn't affect the page's URL.

The TOC (table of contents) level lets you specify how deeply into the article's heading levels the table of contents automatically displayed on the page should go. By default, heading levels <h2> through <h4> are included in the TOC, so that the TOC has a three-level depth. However, you can set this to any of those, as well as "No TOC" (to not display a TOC at all, such as on landing pages) or to show all levels in the TOC.

As is the case with all changes you might make, changes in the page info box do not take effect unless you save the page.

The toolbar

The editor's toolbar offers features that let you adjust the appearance and flow of the article as you work. There are two rows of buttons (more if the width of your window is narrow enough that they wrap, but generally two) and a third row that shows the hierarchy of HTML elements leading up to where you are. In the screenshot below, for example, you're writing inside a top-level <p> block.

The toolbar's buttons are divided into seven groups. Let's look at each; we will examine the buttons in each group in order left-to-right.

Document options

The document options box provides options for document-level manipulations:

Source mode toggle

The source mode toggle button lets you toggle between editing using the WYSIWYG interface and in raw HTML source mode. We strongly request that you try to avoid using source mode, as it's very easy to wind up with content that doesn't match our style guide or, worse, doesn't work right at all. Currently, though, the editor has some quirks that make it impossible to do certain things without resorting to source mode.

Save and keep editing

A duplicate for the main "Save and keep editing" button.

Save and exit

Just like the main "Save changes" button.

Paste as plain text

Opens a dialog into which you can paste text; the text has all styling stripped from it so that you don't inadvertently introduce unwanted styles into the site content. Once you've pasted your text, you can (optionally) make changes, then click a button to insert it into the article you're working on.

Paste from Word

On Windows, lets you paste text from Microsoft Word and have it adjusted to work reasonably well in MDN's wiki. We prefer for you to not use this (the results will work but are not typically style guide compliant), but it's there for a few teams that need it.

Check spelling

Starts the spell checker.

Spell check as you type

Presents a submenu that lets you control and configure the as-you-type spell checker.

Find

Opens the Find panel in "Find" mode, which lets you search your document for a specified string.

Replace

Opens the Find panel in "Find and replace" mode, allowing you to find strings and replace them with new ones.

It's worth noting that the Find and Replace buttons both take you to the same dialog box, which offers several configurable options for finding and optionally replacing text.

Block-level options

These buttons provide options affecting or creating blocks in your article.

Insert/remove bulleted list

Creates or removes a bulleted list from your article. Once you're working in a bulleted list, each time you press return, you will start a new bullet. The tab key can be used to indent a level, and shift-tab will outdent a level. Pressing return on an empty bullet will exit bullet list mode. Right-clicking on the list lets you choose to edit the list's properties (specifically, the shapes of the bullets).

Insert/remove numbered list

Creates or removes a numbered list from your article. Once you're working in a numbered list, each time you press return, you will start a new bullet. The tab key can be used to indent a level, and shift-tab will outdent a level. Pressing return on an empty bullet will exit numbered list mode. Right-clicking the list offers the option to open the properties dialog for the list; the properties include the style of the numbers (numbers, letters, Roman numerals, etc, and what number to start with).

Definition list

Creates a new definition list. Definition lists consist of a series of titles and definitions (this list you're reading right now is an example).

Definition title

Creates a new title in a definition list. If you're not already editing a definition list, a new one is created for you. Pressing return after entering a definition title automatically starts you editing a definition description.

Definition description

Creates a new description in a definition list. Pressing return on a description line automatically starts a new title. Pressing return twice will exit definition list mode.

Decrease indent

Shifts the indentation level to the left once; this is the same as shift-tab while in a list.

Increase indent

Shifts the indentation level to the right once; this is the same as tab while in a list.

Blockquote

Inserts a blockquote. Please do not use this. Blockquotes are not part of our standard style guide, and this button will be removed in the near future.

Image

Inserts a new image into the article. See Adding images to an article below for details on how to use this option.

Table

Inserts a table into the article. See Working with tables for more information on tables in articles.

Text color

Lets you set the text foreground color. Please do not use this. We will switch to using CSS styles for all coloring soon.

Background color

Lets you set the text background color. Please do not use this. We will switch to using CSS styles for all coloring soon.

Text direction left-to-right

Sets LTR as the current text typing direction. Used only when covering localization/internationalization topics.

Text direction right-to-left

Sets RTL as the current text typing direction. Used only when covering localization/internationalization topics.

Maximize

This is an odd box, in that it consists of just one button: Maximize. This button causes the editor interface (that is, the toolbar and the edit box) to take over your entire browser window, giving you as much space as possible to write.

Headings

The heading buttons let you insert a heading. Click one of these buttons to create a new heading at the corresponding depth. By default, H2 through H4 are included in the table of contents, but you can change this, as described in The page info box.

Formatting styles

The next box is a drop-down menu offering a selection of special formatting options. These are:

None

Removes all styling from the current block.

Note box

Creates a note box, as seen below. You should always start a note box with "Note:" in bold letters.

Warning box

Creates a warning box, as seen below. These should always begin with "Warning:" in bold letters.

foo = bar()

Callout box

Creates a new callout box. We are phasing this kind of box out in favor of a new design, so it shouldn't be used for new content.

Two columns

Makes the selected text or the current block two columns instead of one, on browsers that support it.

Three columns

Makes the selected text or the current block three columns instead of one, on browsers that support it.

Syntax box

Creates a syntax box, such as the one shown below. You need to use the "PRE" button as well, to create a <pre> block inside it. You probably won't see the yellow box until you do.

Right sidebar

Special note
This is a right sidebar.

Creates a light grey sidebar that floats to the right of content. You may enter small amounts of text in these boxes to draw special attention to them.

SEO summary

This special style is used to indicate a sentence or two that should be used as the article's summary for SEO purposes. It's also used by macros that automatically construct landing pages. If you don't specify this, MDN automatically uses the first paragraph of your article, but sometimes that's not the optimal text (or it's too much text), so this lets you override that.

Code samples and redirects

These buttons are mostly used for providing preformatted text (usually code samples), but our "insert redirect" button is, for some reason, here too.

PRE

Inserts a <pre> (preformatted text) block, or turns the current block into one. All code samples or examples of text output to a terminal should be in one of these blocks.

Syntax highlighter

The syntax highlighter lets you choose a language for which to apply syntax highlighting to the<pre> (preformatted text) block; if you're not already in such a block, this will create one for you. Simply choose the language and you're good to go.

Insert code sample template

This button is used by the live sample system to help you quickly insert a new live sample. You don't need to use it, but it's there for convenience. See Using the live sample system for details on using this and other live sample features.

Insert code sample iframe

Inserts an <iframe> into the document, displaying a given live sample. See Using the live sample system for details on using this and other live sample features.

Create a redirect

Inserts a redirect. See Creating redirects for further information.

Inline styles and links

The final group of toolbar buttons includes options for creating and maintaining links and anchors, as well as for applying inline styles to content.

Link

Creates a new link. This button opens the link editor dialog, which is covered under Creating and editing links below.

Unlink

Removes the link at the insertion point.

Anchor

Creates an anchor at the insertion point.

Bold

Toggles boldface text mode.

Italic

Toggles italic text mode.

Underline

Toggles underlined text mode.

Code

Toggles <code> mode. This is used for inline presentation of variable names, function names, object names, filenames, and so forth.

Strike through

Toggles strikethrough mode.

Superscript

Toggles superscript mode. Please note that we don't use footnotes on MDN, so you should rarely if ever need this button.

Remove format

Removes the current formatting from the selection.

Align left

Makes the current block left-aligned. Please do not use this. We will be using CSS styles for all alignment tasks starting very soon.

Center

Centers the current block. Please do not use this. We will be using CSS styles for all alignment tasks starting very soon.

Align right

Makes the current block right-aligned. Please do not use this. We will be using CSS styles for all alignment tasks starting very soon.

The edit box

The edit box is, of course, where you actually do your writing. Right-clicking in the edito box will offer appropriate additional options depending on the context of your click; clicking in a table will offer table-related options and clicking in a list will offer list-related options, for example.

The revision comment box

After you've made your changes, it's strongly recommended you add a comment to your revision. This is displayed in the revision history for the page, as well as on the Revision Dashboard. It helps to explain or justify your changes to others that may review your work later. To add a revision comment, simply type the note into the revision comment box before clicking either of the save buttons at the top of the page.

The tags box

Page tags help categorize and organize information, and help us identify pages that need special attention. Tags are also used to mark pages that are obsolete and may need to be deprecated or even deleted. It's incredibly useful to have good, clean tags on pages, so be sure to have good tags on articles you contribute to.

The tag box is near the bottom of the editor page, and looks like this:

Adding a tag

To add a new tag, simply click in the box and start typing:

Here we see the three already existing tags (as button-like objects) and our new tag as unadorned text. When we press Enter or Tab key (or comma), the new tag is committed to the list, and the list looks like this:

For a list of recommended tags, as well as a usage guide for specific tags, please see MDN tagging standards.

Removing a tag

There are two ways to remove a tag: you can click on the "x" icon next to its name in its button, or you can click to its right in the editor box and press the delete key on your keyboard.

Committing your changes

Your changes are not saved unless you click one of the save buttons at the top of the editor window. Scroll back to the top of the window if you don't see the buttons, then click one of the two green save buttons. Now your change has been committed.

The reviews box

MDN uses reviews to try to monitor and improve the quality of its content. This works by setting a flag on an article indicating that a review is needed. You can learn more about technical reviews and editorial review in the How to guides.

To request a review on the article you've worked on, simply toggle on the checkbox next to the type of review that's needed. Technical reviews should be requested any time you make changes to the explanation of how something technical works, while editorial reviews are a good idea when you've made changes and would like someone to review your writing and style choices.

Be sure to click one of the save buttons after making your selections, to commit your review request.

The attachments box

The attachments box lets you upload files to MDN for use in MDN content, as well as see what files are being used by the current document.

To add an attachment to the page, simply click the "Attach Files" button; this expands the attachment box to look like this:

As you see, there's a table that lets you select a file to upload, then give it a title and, optionally, a description and an additional comment. The title is mandatory, and should describe the file so its usage context is understandable. Once the fields are filled out and you've selected your file, click the "Upload" button to send it to MDN.

Feel free to open this page in the editor and look at its attachment list at the bottom to get a feel for it.

Once a file has been attached, it will appear (by its title, as you specified in the form) in the image properties dialog box when using images in your article. See Adding images to an article for details on this interface. To link to other types of files, copy the URL from the attachments box and use that as your link target when adding links to the page using the link button in the toolbar.

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.