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.

We've temporarily disabled SVG uploads due to a security issue. If you need to upload an SVG file, please open a bug and attach the image you'd like to upload.  You can also convert it to a PNG file, which are still allowed.

Note: 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.

Once you've attached an image to the page (see "The attachments box" in Editor UI elements), you can use it in your article. You can also link to images elsewhere on MDN. To insert an image, click on the "Image" button in the toolbar, which looks like this: Toolbar icon for inserting image

The Image Properties dialog box that appears looks like this:

Image properties dialog, with no contents; from CKEditor 4.5.4; border shown.

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

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:

Image properties dialog, Link tab; from CKEditor 4.5.4

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

We've temporarily disabled SVG uploads due to a security issue. If you need to upload an SVG file, please open a bug and attach the image you'd like to upload.  You can also convert it to a PNG file, which are still allowed.

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.

Document Tags and Contributors

Tags: 
 Contributors to this page: jwhitlock, jswisher, Sheppy
 Last updated by: jwhitlock,