---
id: assets
description: Handling assets in Docusaurus Markdown
slug: /markdown-features/assets
---

# Assets

import BrowserWindow from '@site/src/components/BrowserWindow';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Sometimes you want to link to assets (e.g. docx files, images...) directly from Markdown files, and it is convenient to co-locate the asset next to the Markdown file using it.

Let's imagine the following file structure:

```
# Your doc
/website/docs/myFeature.mdx

# Some assets you want to use
/website/docs/assets/docusaurus-asset-example-banner.png
/website/docs/assets/docusaurus-asset-example.docx
```

## Images {#images}

You can display images in three different ways: Markdown syntax, CJS require, or ES imports syntax.

```mdx-code-block
<Tabs>
<TabItem value="Markdown syntax">
```

Display images using simple Markdown syntax:

```md
![Example banner](./assets/docusaurus-asset-example-banner.png)
```

```mdx-code-block
</TabItem>
<TabItem value="CommonJS require">
```

Display images using inline CommonJS `require` in JSX image tag:

```jsx
<img
  src={require('./assets/docusaurus-asset-example-banner.png').default}
  alt="Example banner"
/>
```

```mdx-code-block
</TabItem>
<TabItem value="Import statement">
```

Display images using ES `import` syntax and JSX image tag:

```jsx
import myImageUrl from './assets/docusaurus-asset-example-banner.png';

<img src={myImageUrl} alt="Example banner" />;
```

```mdx-code-block
</TabItem>
</Tabs>
```

All of the above result in displaying the image:

<BrowserWindow>

![My image alternative text](../../assets/docusaurus-asset-example-banner.png)

</BrowserWindow>

:::note

If you are using [@docusaurus/plugin-ideal-image](../../api/plugins/plugin-ideal-image.md), you need to use the dedicated image component, as documented.

:::

## Files {#files}

In the same way, you can link to existing assets by `require`'ing them and using the returned URL in `video`s, `a` anchor links, etc.

```md
# My Markdown page

<a target="\_blank" href={require('./assets/docusaurus-asset-example.docx').default}> Download this docx </a>

or

[Download this docx using Markdown](./assets/docusaurus-asset-example.docx)
```

<BrowserWindow>

<a
  target="_blank"
  href={require('../../assets/docusaurus-asset-example.docx').default}>
  Download this docx
</a>

[Download this docx using Markdown](../../assets/docusaurus-asset-example.docx)

</BrowserWindow>

:::info Markdown links are always file paths

If you use the Markdown image or link syntax, all asset paths will be resolved as file paths by Docusaurus and automatically converted to `require()` calls. You don't need to use `require()` in Markdown unless you use the JSX syntax, which you do have to handle yourself.

:::

## Inline SVGs {#inline-svgs}

Docusaurus supports inlining SVGs out of the box.

```jsx
import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;
```

<BrowserWindow>

import DocusaurusSvg from '@site/static/img/docusaurus.svg';

<DocusaurusSvg />

</BrowserWindow>

This can be useful if you want to alter the part of the SVG image via CSS. For example, you can change one of the SVG colors based on the current theme.

```jsx
import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg className="themedDocusaurus" />;
```

```css
[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] {
  fill: greenyellow;
}

[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
  fill: seagreen;
}
```

<BrowserWindow>
  <DocusaurusSvg className="themedDocusaurus" />
</BrowserWindow>

## Themed Images {#themed-images}

Docusaurus supports themed images: the `ThemedImage` component (included in the themes) allows you to switch the image source based on the current theme.

```jsx
import ThemedImage from '@theme/ThemedImage';

<ThemedImage
  alt="Docusaurus themed image"
  // highlight-start
  sources={{
    light: useBaseUrl('/img/docusaurus_light.svg'),
    dark: useBaseUrl('/img/docusaurus_dark.svg'),
  }}
  // highlight-end
/>;
```

```mdx-code-block
import useBaseUrl from '@docusaurus/useBaseUrl';
import ThemedImage from '@theme/ThemedImage';

<BrowserWindow>
<ThemedImage
  alt="Docusaurus themed image"
  sources={{
    light: useBaseUrl('/img/docusaurus_keytar.svg'),
    dark: useBaseUrl('/img/docusaurus_speed.svg'),
  }}
/>
</BrowserWindow>
```

### GitHub-style themed images {#github-style-themed-images}

GitHub uses its own [image theming approach](https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/) with path fragments, which you can easily implement yourself.

To toggle the visibility of an image using the path fragment (for GitHub, it's `#gh-dark-mode-only` and `#gh-light-mode-only`), add the following to your custom CSS (you can also use your own suffix if you don't want to be coupled to GitHub):

```css title="src/css/custom.css"
[data-theme='light'] img[src$='#gh-dark-mode-only'],
[data-theme='dark'] img[src$='#gh-light-mode-only'] {
  display: none;
}
```

```md
![Docusaurus themed image](/img/docusaurus_keytar.svg#gh-light-mode-only)![Docusaurus themed image](/img/docusaurus_speed.svg#gh-dark-mode-only)
```

<BrowserWindow>

![Docusaurus themed image](/img/docusaurus_keytar.svg#gh-light-mode-only)![Docusaurus themed image](/img/docusaurus_speed.svg#gh-dark-mode-only)

</BrowserWindow>

## Static assets {#static-assets}

If a Markdown link or image has an absolute path, the path will be seen as a file path and will be resolved from the static directories. For example, if you have configured [static directories](../../static-assets.md) to be `['public', 'static']`, then for the following image:

```md title="my-doc.md"
![An image from the static](/img/docusaurus.png)
```

Docusaurus will try to look for it in both `static/img/docusaurus.png` and `public/img/docusaurus.png`. The link will then be converted to a `require()` call instead of staying as a URL. This is desirable in two regards:

1. You don't have to worry about the base URL, which Docusaurus will take care of when serving the asset;
2. The image enters Webpack's build pipeline and its name will be appended by a hash, which enables browsers to aggressively cache the image and improves your site's performance.

If you intend to write URLs, you can use the `pathname://` protocol to disable automatic asset linking.

```md
![banner](pathname:///img/docusaurus-asset-example-banner.png)
```

This link will be generated as `<img src="/img/docusaurus-asset-example-banner.png" alt="banner" />`, without any processing or file existence checking.
