Images and Diagrams

Images

All image files must be placed in /src/images in full original resolution and quality. Multiple compressed and lower resolution files are generated automatically when building the website.

You use standard markdown syntax to insert images into content pages.

It is good to have a meaningful alt text when using images. A meaningful alt text is useful for visually impaired users using softwares to read text on a page.

  • You can add a caption to images by following the Markdown syntax for titles.
  • Images with a transparent background (PNG) are rendered on white background. It's OK to leave transparent background
  • SVG images are not optimized or scaled, but would still be rendered. They need to be placed into /src/files/ for unprocessed delivery.
Full example with alt text title:
![a large dog](/images/dog.jpg 'This dog serves as an example image and this is the title text')
Full SVG example:
![illustation of a shoppin cart](/content/files/cart.svs 'We love illustrated shopping carts')

a large dog
This dog serves as an example image and this is the title text

Unless not otherwise possible, avoid:

  • images on external servers (not optimized, can disappear)
  • images of small sizes or large heights

Mermaid Diagrams

It's possible to create diagrams using mermaid syntax directly in the MDX files. For example, it's possible to create sequence diagrams, flowcharts, class diagrams, ER diagrams, state diagrams and others.

To author, either use mermaid.live or install the mermaid VSCode plugin to get syntax support while writing.

Avoid custom CSS or theme overrides for better maintainability of the content.

```mermaid
sequenceDiagram
Alice->John: Hello John, how are you?
loop Every minute
John-->Alice: Great!
end
```