Skip to main content

Graphics

This topic helps you add screenshots, diagrams, and icons to your content.

For procedures and callouts, see Basic text elements.
For code, tabs, tables, and expandables, see Code and data.

Choosing a pattern​

Reader needRecommended structure
Image for illustration![alt](/img/…)
Sized figure + visible caption<figure> + <img width> + <figcaption>
Icon inside a sentenceSmall <img> with empty alt when the text already names it
Icon or logo that must change in dark modeThemedImage, or one SVG using currentColor
Using HTML

Use HTML in MDX for sizing, captions, and inline icons. Use the ThemedImage theme component when light and dark need different files.

Adding a Markdown image​

Add assets under static/img/ (URL path /img/…). Create subfolders if necessary.

![Docusaurus logo](/img/docusaurus.png)

Docusaurus logo

Always write meaningful alt text for informative images. Use alt="" only for decorative icons when the sentence already names them.

Adding a sized figure with a caption​

<figure>

<img
  src="/img/undraw_docusaurus_tree.svg"
  alt="Small Docusaurus tree illustration"
  width="220"
/>

<figcaption>Figure 1. Example figure from static/img with a limited width.</figcaption>
</figure>
Small Docusaurus tree illustration
Figure 1. Example figure from static/img with a limited width.

Adding an inline icon​

Click the logo <img src="/img/logo.svg" alt="" width="18" height="18" style={{verticalAlign: 'middle'}} /> in the navbar to return home.

Click the logo in the navbar to return home.

Nesting a drawing under a list item​

  • Confirm branding assets are present in static/img.

    Small React / Docusaurus illustration nested in a list item

  • Then link those assets from the relevant topic pages.

Using images in light and dark mode​

Some graphics stay readable on both themes. Others (dark logos, black icons, light-on-white diagrams) disappear or look wrong in dark mode.

When to provide a theme-aware asset​

AssetPractice
Brand mark or inline icon that is dark-on-lightLight + dark files with ThemedImage, or one SVG that uses currentColor
Screenshot of a product UIOne version is usually enough; note the theme in the caption if it matters
Photo or complex illustrationOne version if contrast works on both backgrounds; duplicate only if it fails

Avoid CSS filter: invert() on photos or detailed drawings — use proper light/dark assets instead.

Two files with ThemedImage​

Store both versions under static/img/ (for example logo.svg and logo-dark.svg). In MDX:

import ThemedImage from '@theme/ThemedImage';
import useBaseUrl from '@docusaurus/useBaseUrl';

Click the logo{' '}
<ThemedImage
  alt=""
  sources={{
    light: useBaseUrl('/img/logo.svg'),
    dark: useBaseUrl('/img/logo-dark.svg'),
  }}
  width={18}
  height={18}
  style={{verticalAlign: 'middle'}}
/>{' '}
in the navbar to return home.
Naming

Use a clear pair: icon-name.svg / icon-name-dark.svg, or a light/ and dark/ folder under static/img/.

One SVG with currentColor​

For simple monochrome icons, you can edit them to inherit the colour. To do so, open your SVG editor of choice, and set fill or stroke to currentColor in the SVG.
The icon then follows the surrounding text colour in light and dark mode — no second file and no ThemedImage. Prefer this for UI glyphs. Prefer ThemedImage when the light and dark artwork actually differ (full-colour brand marks, multi-tone icons).

On this page: