mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 18:27:56 +02:00
158 lines
4.2 KiB
Text
158 lines
4.2 KiB
Text
---
|
|
id: assets
|
|
title: Assets
|
|
description: Handling assets in Docusaurus Markdown
|
|
slug: /markdown-features/assets
|
|
---
|
|
|
|
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, JSX require or ES imports syntax.
|
|
|
|
Display images using simple Markdown syntax:
|
|
|
|
```mdx
|
|
|
|
```
|
|
|
|
Display images using inline CommonJS `require` in JSX image tag:
|
|
|
|
```mdx
|
|
<img
|
|
src={require('./assets/docusaurus-asset-example-banner.png').default}
|
|
alt="Example banner"
|
|
/>
|
|
```
|
|
|
|
Display images using ES `import` syntax and JSX image tag:
|
|
|
|
```mdx
|
|
import myImageUrl from './assets/docusaurus-asset-example-banner.png';
|
|
|
|
<img src={myImageUrl} alt="Example banner" />
|
|
```
|
|
|
|
This results in displaying the image:
|
|
|
|
|
|
|
|
:::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 requiring them and using the returned url in videos, links etc.
|
|
|
|
```mdx
|
|
# 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)
|
|
```
|
|
|
|
<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)
|
|
|
|
## Inline SVGs {#inline-svgs}
|
|
|
|
Docusaurus supports inlining SVGs out of the box.
|
|
|
|
```jsx
|
|
import DocusaurusSvg from './docusaurus.svg';
|
|
|
|
<DocusaurusSvg />;
|
|
```
|
|
|
|
import DocusaurusSvg from '@site/static/img/docusaurus.svg';
|
|
|
|
<DocusaurusSvg />
|
|
|
|
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
|
|
html[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] {
|
|
fill: greenyellow;
|
|
}
|
|
|
|
html[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
|
|
fill: seagreen;
|
|
}
|
|
```
|
|
|
|
<DocusaurusSvg className="themedDocusaurus" />
|
|
|
|
## 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 {5-8}
|
|
import ThemedImage from '@theme/ThemedImage';
|
|
|
|
<ThemedImage
|
|
alt="Docusaurus themed image"
|
|
sources={{
|
|
light: useBaseUrl('/img/docusaurus_light.svg'),
|
|
dark: useBaseUrl('/img/docusaurus_dark.svg'),
|
|
}}
|
|
/>;
|
|
```
|
|
|
|
```mdx-code-block
|
|
import useBaseUrl from '@docusaurus/useBaseUrl';
|
|
import ThemedImage from '@theme/ThemedImage';
|
|
|
|
<ThemedImage
|
|
alt="Docusaurus themed image"
|
|
sources={{
|
|
light: useBaseUrl('/img/docusaurus_keytar.svg'),
|
|
dark: useBaseUrl('/img/docusaurus_speed.svg'),
|
|
}}
|
|
/>
|
|
```
|
|
|
|
## 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"
|
|
|
|
```
|
|
|
|
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 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.
|