Getting Started

Use images in Brainports docs

Store shared documentation assets in the images folder, follow naming conventions, and embed images from MDX using markdown or HTML.

What belongs in the images folder

Store shared documentation assets in the images/ folder so any MDX page can reference them. Typical files include:

UI screenshots
Diagrams and architecture visuals
Logos or branded illustrations
Generic placeholders and reusable icons

Keep one canonical copy of each asset in images/ instead of duplicating files in multiple directories.

Prefer SVG for diagrams, icons, and simple graphics because SVG files stay sharp at any size and are usually smaller than PNGs. For photos or complex screenshots, use compressed PNG or JPEG and keep file sizes as small as practical.

Naming conventions

Use descriptive, kebab-case filenames so contributors can quickly identify the right asset:

feature-flows-dashboard.svg
spaces-sidebar-collapsed.png
admin-settings-access-control.png

Avoid generic names like image1.png or screenshot-final.png. When the image relates to a specific page or concept, include that in the name.

Reference images from MDX

Reference files in images/ using site-root paths that start with /images/....

Markdown image syntax

Use standard markdown for most images:

![Spaces overview diagram](/images/placeholder.svg)

This renders the placeholder image with accessible alt text Spaces overview diagram.

HTML img tag

Use an HTML img tag when you need extra control (for example, width or height):

<img
  src="/images/placeholder.svg"
  alt="Spaces overview diagram"
  width="640"
  height="360"
/>

Set alt text to describe the content or purpose of the image, not the filename. For decorative images that convey no information, leave alt empty (alt=""), but avoid decorative images in docs when possible.

Was this page helpful?

Last updated today

Built with Documentation.AI