Attachments in the MDN editor

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

This section is visible (at the bottom of the page) only if you have the required permissions to attach files to pages. Users don't get this permission by default, so if you have a need to attach files, please email the MDN admins to request permission.

The attachments section is also visible only when editing an existing article. It does not appear in the editor for a new article.

Workflow for attachments

The way the attachment upload functionality works results in the page being refreshed after each upload. If you had any unsaved edits made to the page at this point, they might be lost. It is therefore a good idea to save your edits first before uploading attachments.

A good workflow is as follows:

  1. Make edits, creating placeholder text in locations where you want to insert images.
  2. Save your edits.
  3. Attach your images.
  4. Insert the images in place of the placeholders.
  5. Save your work again just to be sure.

If you had unpublished changes when uploading an attachment, they should have been saved as a draft, which you can recover by clicking the Restore draft link at the top of the Edit box. Or you can click Publish and Keep Editing before uploading an attachment. They might be lost if you leave them too long or forget to recover however, hence we recommend the workflow above.

The attachments UI

To add an attachment to the page, click the Upload Files button; this expands the attachment section to look like this:

Screenshot of the Attachments section of the editor, with controls for uploading a file

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 association with the context is understandable. Once the fields are filled out and you've selected your file, click the Upload button to send it to MDN.

The most common use case for attachments is to add images to pages. 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, as a handy Web tool.

Only a select few types of files are permitted as attachments on MDN: GIF, JPEG, PNG, and HTML. Photoshop images are permitted but should be avoided except in very specific cases. Any other file types is not allowed by the upload form. Uploading SVG files requires special permission, so contact the MDN writing team if you need to upload an SVG file.

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 adding images in your article. See Images for details on this interface.

Restricted access

There is obvious potential for vandalism and spam by uploading images that don't belong on MDN Web Docs, so this tool is not available to all users.

Roles that have this privilege

Conditions for gaining this privilege

You can obtain access to this tool if you meet the following conditions:

  • You have a regular need for it (for example, if you are actively working on a set of pages that need numerous image attachments). If you only occasionally need to attach an image, just ask an admin to do it.
  • You edit MDN regularly, and have a track record of constructive contributions.

See Requesting elevated privileges for the process for gaining this privilege.