Visual elements

Screenshots, diagrams, videos, and other visual elements can help your readers better understand instructions and concepts.

Images

Use the <img> element or the standard Markdown notation for inserting images: ![]().

To insert an image from the designated images directory, reference the image by its name:

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

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

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

                    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:

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

                    ![Alt Text](https://www.jetbrains.com/company/brand/img/jetbrains_logo.png){ width="450" }
                

The <img> element has the following attributes:

src

Specify the name of the file from the images directory or its subdirectories. Completion always suggests these files before any others.

You can specify the path to any image file in your project relative to the current topic file using ./ or ../. In this case, you will see helpful path completion suggestions.

You can also specify a URL to a file hosted somewhere on the web. In this case, make sure that the file is accessible from where you are going to host your documentation.

For Markdown, specify the file in the round brackets:

![Alt Text](image.png)

alt

Add alternate text for an image. This is a short description of the image, which is rendered when the image cannot be displayed, used by screen readers, and helps with search optimization.

For Markdown, put alternate text in the square brackets:

![Alt Text](image.png)

width

Specify the image width. By default, images are rendered in their actual size or shrink to fit the viewport. The height is adjusted proportionally, unless you set it explicitly.

height

Specify the image height. By default, images are rendered in their actual size or shrink to fit the viewport. The width is adjusted proportionally, unless you set it explicitly.

border-effect

Add a border effect to the image. For example, if a screenshot shows an area rather than an entire dialog, the background may blend in, so it is a good idea to add a border around the image. Rather than editing the image source, Writerside can add borders to your image.

Possible values:

none is the default value, which does not add a border to the image.
line adds a rectangular border along the edges of the image.
rounded adds a border with rounder corners.

GIF animations always have a border, so none is not applicable for them.

style

Override the default behavior derived from image size. Possible values are block and inline.

Any image up to 32 pixels located in a paragraph is considered an inline image by default and it is rendered inside the paragraph. For example:

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

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

If you want to render a large image inline, set style="inline":

thumbnail

Render a thumbnail of the original image if it is larger than the viewport of the current component. When your reader clicks the thumbnail, it will expand to the full size image.

preview-src

Set a custom preview file for the image instead of an automatically generated thumbnail.

Animated GIFs

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

![Alt Text](animation.gif)

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

Light and dark theme

Documentation built and published with Writerside has a switcher in the header 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.

Image example with light and dark version

Provide images for the dark theme

Add the _dark.png suffix to the name of the dark image version. For example, save images as example.png and example_dark.png.
Put both image files to the images directory in your project.
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 to open the Insert menu, and then select Image to insert an image. Alternatively, press Ctrl+U to open the Insert Image dialog directly.

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

In Markdown, you can use reference-style links to insert images used multiple times within 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
                [up]: up-icon.png
                [down]: down-icon.png
                [plus]: plus-icon.png
            

The previous example will render as:

Click the icon to mark an item as done.

Videos

Use the <video> element to add a local video or a video from YouTube or Vimeo.

The <video> element has the following attributes:

src: Specify the name or path to a local video file or a URL to a YouTube or Vimeo video. For YouTube, you can use both the full and the shortened link formats.
width: Set the width of the video element.
height: Set the height of the video element.
preview-src: Specify a custom image for the preview. By default, YouTube videos use the thumbnail specified when the video was uploaded.
mini-player: Enable the mini-player to hide all video controls except the play and pause button. This is useful for short videos used instead of animated GIFs.
<video src="sample.mp4" mini-player="true" preview-src="preview-image.png"/>

Last modified: 28 November 2023