Attachments in the MDN editor

EdThe 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 only visible 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 file a bug and request permission.

The attachments section is also only visible 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.
  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 us recommending 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 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.

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, a handy Web tool.

Only a select few types of files are permitted as attachments on MDN: GIF, JPEG, PNG, SVG, 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.

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.

Document Tags and Contributors

 Contributors to this page: chrisdavidmills, jswisher
 Last updated by: chrisdavidmills,