This article introduces new contributors to the process of editing existing pages and creating new ones.
Editing an existing page
To edit a page:
- Click the Edit button near the top right corner of the page.
- The page then reloads, with an editing interface where you can add or delete information directly.
- Add paragraphs, delete text, insert headings, and perform more of the basic functions involved in writing and editing.
To see what your changes look like:
- Click the Preview button, within the editing function at the top or bottom of the page.
- This opens the preview page, showing your revisions in a new window, or tab.
- Each time you click this button, it refreshes your preview page with the latest changes.
Be careful! Previewing a page does not save your progress. Don't close the editing tab until you've saved your work.
After previewing your changes, you will want to save your revision. Before you save, look for the revision comment box, below the editing box, leaving a comment to inform other contributors why you made 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.
Table of Contents
The 'In this Article' section of an article, is an auto-generated list of links to the headings on the page. The wording of these can be edited via the headings. It's also possible to remove a table of contents, or decrease its number of links, by selecting 'Edit Page Title and Properties', changing the value of the "TOC" drop down.
You can add or remove tags, which describe the page content and purpose, below the editing section. See How to properly tag pages, for information on which tags to apply.
If an expert, or experienced contributor should review your edits, please request a technical review (for code, API's, or technologies), and/or an editorial review (for prose, grammar, and content), making sure the appropriate box is checked before you save.
If you wish to attach a file to an existing page, or to add an illustration for further clarification, this can be added to 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 finish editing, and are happy with your preview, publish your work and comments by clicking the green Publish button, to the right of the page title, or towards the bottom of the page. If you wish to continue working, click Publish and keep editing, which publishes your changes and keeps the edit interface open.
If you change your mind, you can discard 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.
Note: If attempting to save, but changes are rejected as invalid, and you feel the content is appropriate for MDN, email the MDN admin team for assistance.
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 get the page created. There are two options:
- Ask for the page to be created for you. To do this, file a documentation request issue, with the title "Create page: <page title>". Fill out the URL field of the template with the location on MDN where you'd like the page to go, if you know where to place it. In the comment text, include information on why this page needs creating.
- Request page creation privileges. If you request page creation privileges, and they're granted to you, you'll be able to add new pages by following the instructions here. To request these privileges, email the MDN admin team with your request. 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 made useful contributions to this site's content, and been a contributor for some time. This length of time, and the other factors, are collectively considered.
Creating a new page
Once you have page-creation permission, you can begin creating pages.
If you do not know where to place a new article, do not worry. Put it anywhere, we will find it, move to where it belongs, or merge it into existing content. Whatever makes the most sense. Do not worry about making it perfect. We have happy helper gnomes who help making your content clean and rather 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.
'Missing page' link
As with most wikis, it is possible to create a link to a page that is yet to 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:
- Log into MDN, and have page-creation permission. If not logged in, clicking a 'missing page' link results in 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:
MDN creates a new page, with the title "FooBar", opening the editor for you to add new content. Refer to the Editing an existing page section of this article, for information on how to use the editor mode.
To create a new page without linking from another page:
- Log in, and have page-creation permission.
- Enter the following in the URL field of your browser:
MDN creates a new page, with a place for a title, opening the editor to add new content to this page. Refer to Editing an existing page, for information on using editor mode.
Subpage of an existing page
To create a page 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), then click New sub-page.
- An editor view opens for creating a new document.
- Add a title for this document, in the Title field.
- Change the Slug field, if needed. For example, if the title is long, and a shorter URL seems appropriate. This field is automatically filled by the editor, substituting underscores for spaces found in the title, changing only the last part of the URL.
- In the TOC field, select heading levels you want to be displayed in the table of contents for the page. Or select 'No table of contents', if one is not needed.
- Write content of the page in the editor pane, saving your changes. Refer to Editing an existing page, for further information on using editor mode.
Clone of an existing page
If there is an existing page, whose format you wish to use as a base for your new page, you can 'clone' that page, and then change its 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.
- Change the path portion of the Slug field, as needed, to put the new document in a different location in the document hierarchy. In most cases, this is not needed. A cloned page often has similar content to its original, and need to be in a similar location.
- In the TOC field, select the heading levels you want to be automatically displayed in the table of contents for this page. Or select 'No table of contents', if one is not needed.
- Write your content in the editor pane, saving your changes. Refer to Editing an existing page, for more information on using editor mode.
Link from an existing page
This is a bit of a hybrid. You can create a link on another page, then click the link you just inserted, to create the new page:
- Enter the name of your new page, anywhere that makes sense in the text of an existing page.
- Highlight this new 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, to the beginning of the URL field. Enter the name of the page after "/en-US/docs/". The page name does not have to be the same as the link text.
- Click OK, to create and insert the link.
If the page does not yet exist, the link is displayed in red. If the page does exist, the link is displayed blue. If you want to create a new page, but the page title you desire is already taken, check if it makes sense helping edit and improve the page already there. Otherwise, think of a unique title for your new page, and create a link for it. Refer to 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, enabling you to start writing. Refer to Editing an existing page, for further information on using editor mode.
Refreshing page content
MDN support of KumaScript macros, and integration of content from other pages, can sometimes be hampered by the need for caching of pages, for performance reasons. Pages are built from their source, and this output is cached for future requests. From that moment on, any macros (templates), or integrations (using the macro
Page), will not reflect later changes made to the macro, its output, or the contents of the integrated material.
- To manually update a page, force-refresh your Web browser. MDN detects this, triggering a page rebuild, pulling in updated macro output, and integrating page content.
- You can also configure pages to periodically rebuild, automatically. This should not be done, unless you expect the page to update frequently. See Page regeneration, for detailed information.