Images

It's frequently useful to include images in articles. Images may be screenshots, examples of what a rendering should look like, or SVG diagrams of program flow, for example. This article describes how to use images in MDN content.

Workflow for attaching images

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 images.

A good workflow is as follows:

1. Make edits. Mark places where an image needs inserting with a placeholder, e.g. [EXAMPLE OUTPUT IMAGE HERE].
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.

Attaching an image to an article

Once you've attached an image to the page (see Attachments), you can use it in your article. You can also link to images elsewhere on MDN. To insert an image, click  the Image button in the toolbar, which looks like this:

The Image Properties dialog box appears, which looks like this:

There are three tabs; the first (and the one you'll use most) is the Image Info tab. The other two are the Link and Advanced tabs.

Image Info

There are many options here:

Attachments

This popup menu shows a list of the page attachments. Only items you've uploaded during the current editing session, or that are already used elsewhere on the page, are listed.

URL

If you wish to use an image that's not in the attachments list (for example, one attached to a different article on MDN, or uploaded during a previous editing session), you can enter its URL in this field.

Alternative text

The alternative text to be displayed if the image is not displayed. This text is also used by screen readers, so please put an appropriate note here for the sake of accessibility.

Width / Height

You may adjust the width and height of the image as displayed in the article here. By default, these are locked to remain in proportion to one another, but you may toggle that by clicking on the lock icon.

Border

You may optionally specify the width of a black border to draw around your image. Please only use the value 0 (or leave blank) or 1 here. Only use a border if your image has a pale background and needs to stand out from the the article's background.

HSpace / VSpace

These let you specify how much whitespace to surround the image with horizontally and vertically, respectively. You usually only need to use these if you use the alignment option below.

Alignment

By default, images are displayed alone as their own block. However, you may choose here to float the image to the left or to the right, allowing text to wrap around it. We don't do this often; it's used only in very special cases where the image is small (or very narrow and tall) and there's enough text to put next to it to fill the vertical space. This is a bit of a judgement call. If you use this option, you will probably want to set HSpace and VSpace values to prevent the text from being too close to the image. A value of 6 or 8 for each usually works well.

The preview box gives an example of what the image will look like given your current settings.

Link

The Link tab for images lets you set a URL to go to when the image is clicked. This is most commonly used to simply link to a larger version of the image itself (by providing the same URL as in the Image Info tab). The Link tab looks like this:

URL

Address of a location that the browser navigates to when the user clicks the image.

Target

The browsing context in which to open the specified URL; values correspond to the target attribute of the <a>. Please do not use this field on MDN. We prefer that all links to open in the same tab.

Supported image types

You may upload GIF, JPEG, and PNG images, as well as SVG diagrams. The preferred image types on MDN are:

• PNG for screenshots
• SVG for diagrams, because they can be translated into other languages more easily than other image types

Photoshop files may also be uploaded. However, they may not be used as images inline in content. They are only available for download.

Removing and changing images

To remove an image from the article, you can select it or place the cursor after it, and press the Delete key.

You can also revise the image properties for an image by double-clicking it, or right-clicking on it and choosing Image Properties on the context menu that appears. This presents the same dialog as above.

Only MDN administrators can delete attachments. In general, we leave old versions of images in place, because they may be referenced by old revisions of documents. If you find inappropriate or proprietary images on MDN, please contact an MDN admin to remove the attachment, or file a bug to have it removed.

Image optimization tools

Here are a few tools that you may consider using to optimize images:

• TinyPNG (Web)
• ImageOptim (Web, macOS)
• Trimage (Linux)