# Images

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/writerside/llms.txt).

Visualizing content with screenshots, animations, and diagrams can help your readers better understand instructions and concepts.

To add an image, use the  [<img>](semantic-markup-reference.html#img)  element or the standard Markdown notation for images: `![]()`.

> **Note:**
> Writerside supports images in PNG, JPG, GIF, and SVG formats.

If the image is in the designated  [images directory](help-modules.html#images-dir) , reference the image by its name:

Semantic markup:

```XML
<img src="image.png" alt="Alt text" width="450"/>
```

Markdown:

```PLAINTEXT
![Alt Text](image.png){ width="450" }
```

> **Tip:**
> You can also paste an image from the clipboard directly into the editor. Writerside will suggest saving the image to the  [images directory](help-modules.html#images-dir)  and add the necessary markup for it at the location of the caret.

To insert an image relative to the current topic, use a relative path:

Semantic markup:

```XML
If the image and topic file are in the same directory:
<img src="./image.png" alt="Alt text" width="450"/>

If the image is in some other location:
<img src="../myMediaDir/image.png" alt="Alt text" width="450"/>

Or relative to the project root:
<img src="$PROJECT_DIR$/allImages/image.png" alt="Alt text" width="450"/>
```

Markdown:

```PLAINTEXT
If the image and topic file are in the same directory:
![Alt Text](./image.png){ width="450" }

If the image is in some other location:
![Alt Text](../myMediaDir/image.png){ width="450" }

Or relative to the project root:
![Alt Text]($PROJECT_DIR$/allImages/image.png){ width="450" }
```

To insert an image hosted somewhere on the web, specify a URL to the image file:

Semantic markup:

```XML
<img src="https://www.jetbrains.com/company/brand/img/jetbrains_logo.png" alt="Alt text"/>
```

Markdown:

```PLAINTEXT
![Alt Text](https://www.jetbrains.com/company/brand/img/jetbrains_logo.png)
```

> **Note:**
> There is currently a known issue that you cannot set the size of an externally hosted image. It will be fixed in the future.

## Inline and block images

Use the [style](semantic-markup-reference.html#img_style) attribute to render a large image in a paragraph or a small image as a separate block.

By default, Writerside renders any image larger than 32 pixels as a separate block element, even if you put it inside a paragraph:

![Writerside logo 40 by 40 pixels](https://resources.jetbrains.com/help/img/writerside/writerside.svg)

If you want to render a large image inline, set `style="inline"` to indicate your intent: ![Writerside logo 40 by 40 pixels](https://resources.jetbrains.com/help/img/writerside/writerside.svg)

Any image up to 32 pixels located in a paragraph is considered an inline image, and Writerside renders it inside the paragraph. For example: ![Writerside logo 16 by 16 pixels](https://resources.jetbrains.com/help/img/writerside/writerside.svg)

If you want to render a small image as a separate block, set `style="block"` or put it outside the paragraph according to your intent, like this:

![Writerside logo 16 by 16 pixels](https://resources.jetbrains.com/help/img/writerside/writerside.svg)

## Thumbnails

By default, Writerside resizes images wider than 700 pixels to fit the maximum viewport. If an image is wide and has a lot of details, add the `<thumbnail="true">` attribute to render the image as a clickable thumbnail with a plus icon that expands to its full size on click.

Semantic markup:

```XML
<img src="image.png" alt="Alt text" thumbnail="true"/>
```

Markdown:

```PLAINTEXT
![Alt Text](image.png){ thumbnail="true" }
```

![Wide image](https://resources.jetbrains.com/help/img/writerside/add-live-template.png)

You can specify the size to make the thumbnail even smaller.

Semantic markup:

```XML
<img src="image.png" alt="Alt text" thumbnail="true" width="200"/>
```

Markdown:

```PLAINTEXT
![Alt Text](image.png){ thumbnail="true" width="200" }
```

![Wide image](https://resources.jetbrains.com/help/img/writerside/add-live-template.png)

You can specify a different thumbnail image using the `preview-src` attribute:

Semantic markup:

```XML
<img src="image.png" alt="Alt text" thumbnail="true" preview-src="thumbnail-preview.png"/>
```

Markdown:

```PLAINTEXT
![Alt Text](image.png){ thumbnail="true" preview-src="thumbnail-preview.png" }
```

![Wide image](https://resources.jetbrains.com/help/img/writerside/add-live-template.png)

## Animated GIFs

To insert an animated GIF, add it as a regular image:

Semantic markup:

```XML
<img src="animation.gif" alt="Alt text"/>
```

Markdown:

```PLAINTEXT
![Alt Text](animation.gif)
```

Writerside recognizes the animation and renders the first frame with the `Gif` label on it. Reader can click it to start the animation.

![Animated GIF example](https://resources.jetbrains.com/help/img/writerside/jetbrains.gif)

> **Tip:**
> To use a different image instead of the first frame, set `preview-src="some-preview.png"`.

## Light and dark theme

Documentation built and published with Writerside has a switcher in the header ![Switcher between the light and the dark theme](https://resources.jetbrains.com/help/img/writerside/systemTheme.svg) that lets readers choose between the light and the dark theme. If applicable, provide both the light and the dark version of every screenshot you use in documentation.

Procedure: Provide images for the dark theme

1. Add the `_dark.png` suffix to the name of the dark image version. For example, save images as `example.png` and `example_dark.png`.

2. Put both image files to the designated  [images directory](help-modules.html#images-dir)  in your project.

3. Specify the name of the light image version in the `src` attribute. For example, `<img src="example.png" alt="This image has light and dark versions"/>`.

## Images in Markdown

In Markdown, you can press `Alt+Insert` (Windows), `⌘ N` (macOS), `⌃ N` (IntelliJ IDEA Classic (macOS)), `⌘ N` (macOS System Shortcuts), `Alt+Insert` (XWin), `Alt+Insert` (GNOME), `Alt+Insert` (KDE), `Alt+Insert` (Emacs), `Alt+Insert` (Sublime Text), `⌘ N` (Sublime Text (macOS)), `Alt+Insert` (NetBeans), `Alt+Insert` (Visual Studio), `⌘ ⌃ N` (Visual Studio (macOS)), `Alt+Insert` (Eclipse), `⌘ N` (Eclipse (macOS)) to open the Insert menu, and then select Image to insert an image. Alternatively, press `Ctrl+U` (Windows), `⌘ U` (macOS), `Ctrl+U` (IntelliJ IDEA Classic (macOS)), `Ctrl+U` (macOS System Shortcuts), `Ctrl+U` (XWin), `Ctrl+U` (GNOME), `Ctrl+U` (KDE), `Ctrl+U` (Emacs), `Ctrl+U` (Sublime Text), `Ctrl+U` (Sublime Text (macOS)), `Ctrl+U` (NetBeans), `Ctrl+U` (Visual Studio), `Ctrl+U` (Visual Studio (macOS)), `Ctrl+U` (Eclipse), `Ctrl+U` (Eclipse (macOS)) to open the Insert Image dialog directly.

![Insert Image dialog](https://resources.jetbrains.com/help/img/writerside/insert_image_dialog.png)

Any image that you add to a Markdown topic is marked with an icon in the gutter. Click the icon to configure the image.

![Images in Markdown](https://resources.jetbrains.com/help/img/writerside/images_in_markdown.png)

In Markdown, you can use [reference-style links](links-and-references.html#reference-style-links) to insert the same image multiple times in a topic, such as icons. To do this, declare the image inside that topic with a reference name and reference the image by this name:

```
Click the ![check icon][check]{width="16"} icon to mark an item as done.

[check]: check-icon.png
```

The previous example will render as:

Click the ![check icon](https://resources.jetbrains.com/help/img/writerside/check-icon.png) icon to mark an item as done.