How to create and edit pages

The two most common tasks on MDN, which almost any MDN contributor will eventually perform, are to edit an existing page or to create a new one. This article covers the very basics of how to do each of these.

Editing an existing page

It's easy to edit:

Simply click the Edit button near the top right corner of the page.
The page reloads with formatting options so that you can add or delete information directly on the page.
You can add paragraphs, delete text, insert heading, and perform more of the basic functions involved in writing and editing. See the guide to Editor UI elements in the MDN Editor guide for more information on using MDN's built-in editor.

Preview changes

To see how your changes look like:

Click the Preview changes button (within the editing function) above the page title.
This opens a preview page that includes your revisions in a new window or tab.
Each time you click this button, it refreshes your preview page with your latest changes.

Be careful! Previewing a page does not save your progress, so remember not to close your open editing tab.

Revision comment

After you've previewed your changes, you will want to save your revision. Before you save, look for the revision comment box below the page title section and leave a comment to inform other contributors why you made any changes. For example, you might have added a new section, changed some words to make the terminology more consistent, rewritten a paragraph to clarify the language, or removed information because it was redundant.

Review needed?

If an expert or experienced contributor should review your edits, you can request a technical review (for code, API's, or technologies), an editorial review (for prose, grammar, and content), or a template review (for KumaScript code) by making sure the box is checked before you save.

Attach files

If you wanted to attach a file to an existing page to add an illustration or further clarification, it can be entered at the bottom of the page. When uploading an image, please be sure to use an image optimization tool to make the file as small to download as possible. This improves page load time and helps MDN's performance overall. You may use your preferred tool, if you have one. Otherwise, we suggest TinyPNG, a handy Web tool.

Publish, Discard, or Keep editing

When you are finished editing, and happy with your preview, you can publish your work and comments by clicking the green Publish button to the right of the page title or at the bottom of the page. If you want to continue working, click Publish and keep editing, which publishes your changes while keeping the editing interface open.

If you change your mind, you can discard your edits by clicking the red Discard button. Note that discarding changes permanently discards them.

Pressing Enter in the Revision Comment field is equivalent to clicking Publish and Keep Editing.

If you try to save your page and your changes are rejected as invalid when you try to save them, but the content is in fact appropriate for MDN, you should email the MDN admin team for help getting your content posted.

Creating a new page

If you do not know where to put a new article, do not worry about it! Put it anywhere and we will find it and move it to where it belongs or merge it into existing content if that makes the most sense. You also do not need to worry about making it perfect. We have happy helper gnomes that will help make your content clean and luscious.

There are a few ways to create a new page:

"Missing page" link
New page without link
Subpage of an existing page
Clone of an existing page
Link from an existing page

Getting page creation permissions

For security reasons, newly-created accounts don't have the ability to create new pages. If you try to do so, you'll see a page instructing you how to go about getting the page created. There are two options:

Ask for the page to be created for you. To do this, file a documentation request bug with the subject "Create page: <page title>". Be sure to fill out the URL field with the location on MDN you'd like the page to go at, if you know where to put it. You should include in the comment text some information about why you need the page created.
Request page creation privileges. If you request page creation privileges and they're granted to you, you'll be able to add new pages yourself by following the instructions here. To request these privileges, email the MDN admin team with your request. Be sure to include your username, why you would like to have the ability to create new pages (for instance, you're documenting a new API which involves many new pages, or you'd like to add new terms to the glossary). You should also have already made some useful contributions to the site content, and should have been a contributor for some length of time (the length of time and the other factors are all considered together, so there isn't a fixed time period here).

"Missing page" link

As with most wikis, on MDN it is possible to create a link to a page that doesn't yet exist. For example, an author might create a list of all the members of an API, before creating the pages for those members. On MDN, links to non-existent pages are typically displayed in red.

To create a page from a "missing page" link:

Make sure that you are logged in to MDN. (If you aren't logged in, clicking a "missing page" link gives a 404 (page not found) error.)
Click the "missing page" link. If you have page creation permission, the MDN Editor UI opens, ready for you to create the missing page.
Write the content of the page, and save it.

New page without link

To create a new page without linking from another page, enter a unique page name in the URL field of your browser. For example, if you enter:

https://developer.mozilla.org/en-US/docs/FooBar

MDN creates a new page with the title "FooBar" and opens the editor so you can add content to the new page. Refer to the Editing an existing page section of this article for how to use the editor mode.

Subpage of an existing page

To create a page that you want to be below an existing page in the page hierarchy:

On the "parent" page, click the Advanced menu (the gear icon in the toolbar), and click New sub-page. An editor view opens for creating a new document.
Type a title for the document in the Title field.
Change the Slug field if needed (for example, if the title is very long and you want a shorter URL). This field is automatically filled by the editor, by substituting underscores for spaces in the title. In this case, you can change only the last part of the URL of the document.
In the TOC field, select the heading levels you want to be automatically displayed in the table of contents for the page, or "No table of contents" if the page doesn't need one.
Write content of the page in the editor pane, and save your changes. Refer to the Editing an existing page section of this article for how to use the editor mode.

Clone of an existing page

If there is an existing page whose format you want to use for your new page, you can "clone" that page and then change the content.

On the original page, click the Advanced menu (the gear icon in the toolbar), and click Clone this page. An editor view opens for creating a new document.
Change the Title of the page as appropriate for the new content. The Slug field is updated automatically as you change the Title field.
If needed, change the path portion of the Slug field, to put the new document in a different part of the document hierarchy. (In most cases, this is not needed, because the cloned page has similar content to the original, and therefore should be located in a similar place.)
In the TOC field, select the heading levels you want to be automatically displayed in the table of contents for the page, or "No table of contents" if the page doesn't need one.
Write content of the page in the editor pane, and save your changes. Refer to the Editing an existing page section of this article for how to use the editor mode.

Link from an existing page

This method is a bit of a hybrid. You can create a link on another page, and then click the link you just inserted, to create the new page.

Enter the name of the new page anywhere (that makes sense) in the text of an existing page.
Highlight the name and click the Link icon () in the editor's toolbar. The "Update Link" dialog opens, with the highlighted text in the "Link To" field.
"/en-US/docs/" is inserted by default at the beginning of the URL field. Enter the name of the page after "/en-US/docs/". (The page name doesn't have to be the same as the link text.)
Click OK to create and insert the link.

If the page does not already exist, the link is displayed in red. If the page does already exist, the link is displayed in blue. If you want to create a new page but the page title you want is already taken, check first if it makes more sense to help edit and improve the page that is already there. Otherwise, think of a different title for your new page and create a link for it. Refer to the page naming guide for guidelines.

To add content to your new page, click on the red link you just created (after saving and closing the editor). The new page opens in editor mode, so you can start writing. Refer to the Editing an existing page section of this article for how to use the editor mode.

Refreshing page content

MDN's support for KumaScript macros and transclusion of content from one page into another can sometimes be hampered slightly by the need for caching of generated pages for performance reasons. Pages are built from their source, and that output is cached for future requests. From then on, any macros (templates) or transclusions (using the Page macro on that page will not reflect changes made to the macro, the macro's output, or the contents of the transcluded material.

To update a page manually, you can do a force-refresh in your browser. MDN detects this and triggers a page rebuild, pulling in updated macro output and transcluded page content.
You can also configure pages to periodically be rebuilt automatically. This should not be done unless you expect the page to need updating frequently. See Page regeneration for details.