If you want to add images to your docs, you can add them in a ./img folder in the same directory as your .mdx files. You don't have to follow a rigid folder structure as long as the relative path (starts with ./) to the image is correct. See local images.

If an image is used in multiple places, it's best to put it in includes/common-imgs/imgs and reference it in a local include file to be used in the target mdx file. See common images.

Alternatively, images can also be added to the public folder and referenced using their relative or full path within the folder. See public images

The file, docs/product/alerts/alert-types.mdx, can reference the local docs/product/alerts/img/alert-details-example.png image like so :

![Alert details ...](./img/alert-details-example.png)

Images that are reused in multiple files should be single-sourced as an include file. For example, the common image, includes/common-imgs/imgs/tags.png, is referenced in the include file, includes/common-imgs/tags.mdx, like so:


The image can then be used in multiple places (such as docs/platforms/ruby/common/enriching-events/tags/index.mdx) by referencing the include file with the following syntax:

<Include name="common-imgs/tags" />

While we recommend storing images locally with the files that reference them, you can also put them in the public folder. By default, the docs platform assumes images referenced with paths starting with / live in the public folder, so you don't need to include public in the image path.

The folder structure of public mimics that of docs so that you can reference these images with relative paths. For example, the file, docs/product/alerts/alert-types.mdx, can reference the image, public/product/alerts/issue-alert.png, like so :

![Issue alert](issue-alert.png)

Content files living elsewhere can also reference public images by using their full paths (excluding public). For example, the file, docs/platform/apple/index.mdx, can also reference the same image, public/product/alerts/issue-alert.png, like so:

![Issue alert](/product/alerts/issue-alert.png)

To save space and ensure consistency, we ask that all image files be compressed and cropped to the dimensions listed below. When adding an image, please makes sure that it's high-resolution and crisp and that text is big enough to read.

  • If you want the image to take up the full width of the page, make it 1484 pixels wide.

  • If you want the image to be indented once (for example, if it's under a list item), make it 1400 pixels wide.

For performance reasons, images should be compressed. We recommend using ImageOptim. Here are the steps to follow:

  1. Download and install
  2. Drag and drop your image(s) into the tool. The files will be compressed in place.
  3. Wait until a green checkmark appears, then add the compressed image to the appropriate path in the public folder of the docs repo.
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").