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.
Once you've attached an image to the page (see "The attachments box" in Using the MDN editor), 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:
The image properties dialog box that appears 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.
There are many options here:
- This popup menu shows a list of the page attachments. Only items you've uploaded during the current edit session, or that are already used elsewhere on the page, will be listed.
- 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 edit 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.
- 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, and you should only choose to use a border if your image has a pale background and should 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 will usually only need to use these if you use the alignment option below.
- 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 justify it. 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 options tab for images lets you set a URL to go to when the image is clicked on. 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 panel looks like this:
Other than the URL field, in which you place the URL of the link's destination, you can set a target. However, please do not do so. 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. For screenshots, we prefer PNG, and we're trying to transition to using 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.
Removing and changing images
To remove an image from the article, you can simply select it and press your delete key, or place the cursor after it and press delete.
Note: You cannot delete attachments on MDN; we will eventually have a mechanism for this, but at this time, they remain on the server for potential later re-use.
You can also revise the image properties for an image by double-clicking it, or right-clicking on it and choosing "Image Properties" from the context menu that appears. This will present the same dialog as above.