Ressources

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.

Imaginons la structure de fichier suivante :

# Votre doc
/website/docs/myFeature.mdx

# Quelques ressources que vous voulez utiliser
/website/docs/assets/docusaurus-asset-example-banner.png
/website/docs/assets/docusaurus-asset-example.docx

Images

Vous pouvez afficher les images de trois manières différentes : la syntaxe Markdown, la syntaxe require de CJS ou la syntaxe ES imports.

Markdown syntax

Affichez les images en utilisant la syntaxe simple de Markdown :

![Exemple de bannière](./assets/docusaurus-asset-example-banner.png)

CommonJS require

Display images using inline CommonJS require in JSX image tag:

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

Import statement

Display images using ES import syntax and JSX image tag:

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

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

Toutes les méthodes ci-dessus permettent d'afficher l'image :

http://localhost:3000

remarque

If you are using @docusaurus/plugin-ideal-image, you need to use the dedicated image component, as documented.

Files

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

# 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)

http://localhost:3000

Download this docx

Download this docx using Markdown

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

Docusaurus prend en charge la mise en place de SVG.

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;

http://localhost:3000

Cela peut être utile si vous voulez modifier la partie de l'image SVG via CSS. Par exemple, vous pouvez changer une des couleurs SVG en fonction du thème courant.

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg className="themedDocusaurus" />;

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

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

http://localhost:3000

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.

import ThemedImage from '@theme/ThemedImage';

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

http://localhost:3000

GitHub-style themed images

GitHub uses its own image theming approach 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):

src/css/custom.css

[data-theme='light'] img[src$='#gh-dark-mode-only'],
[data-theme='dark'] img[src$='#gh-light-mode-only'] {
  display: none;
}

![Image à thème Docusaurus](/img/docusaurus_keytar.svg#gh-light-mode-only)![Image à thème Docusaurus](/img/docusaurus_speed.svg#gh-dark-mode-only)

http://localhost:3000

Static assets

Si un lien ou une image Markdown a un chemin absolu, le chemin sera considéré comme un chemin de fichier et sera déterminé à partir des répertoires statiques. For example, if you have configured static directories to be ['public', 'static'], then for the following image:

my-doc.md

![Une image depuis 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. C'est souhaitable à deux égards :

1. Vous n'avez pas à vous soucier de l'URL de base, dont Docusaurus se chargera au moment de diffuser la ressource;
2. L'image entre dans le pipeline de construction de Webpack et son nom sera complété par un hachage, ce qui permet aux navigateurs de mettre l'image en cache de manière agressive et améliore les performances de votre site.

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

![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.