Images
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
Every image path that starts with /
(instead of ./
) is considered to be in the public
folder.
The file, docs/product/alerts/alert-types.mdx
, can reference the local docs/product/alerts/img/alert-details-example.png
image like so :
docs/product/alerts/alert-types.mdx
![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:
includes/common-imgs/tags.mdx
![Tags](./img/tags.png)
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:
docs/platforms/ruby/common/enriching-events/tags/index.mdx
<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 :
docs/product/alerts/alert-types.mdx
![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:
docs/platform/apple/index.mdx
![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:
- Download and install https://imageoptim.com/.
- Drag and drop your image(s) into the tool. The files will be compressed in place.
- Wait until a green checkmark appears, then add the compressed image to the appropriate path in the
public
folder of the docs repo.
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").