Ressources

Parfois, vous souhaitez établir un lien vers des ressources (par exemple des fichiers docx, des images...) directement à partir de fichiers Markdown, et il est pratique de placer la ressource à côté du fichier Markdown qui l'utilise.

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.

Syntaxe Markdown

Affichez les images en utilisant la syntaxe simple de Markdown :

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

require CommonJS

Affichez les images en utilisant en ligne le require de CommonJS dans la balise image de JSX :

<img
  src={require('./assets/docusaurus-asset-example-banner.png').default}
  alt="Exemple de bannière"
/>

Déclaration d'un import

Affichez les images en utilisant la syntaxe import de ES et la balise image JSX :

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

<img src={myImageUrl} alt="Exemple de bannière" />;

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

http://localhost:3000

remarque

Si vous utilisez @docusaurus/plugin-ideal-image, vous devez utiliser le composant d'image dédié, comme documenté.

Fichiers

De la même manière, vous pouvez créer des liens vers des ressources existantes en utilisant require et en utilisant l'URL renvoyée dans les liens video, a, etc.

# Ma page Markdown

<a target="\_blank" href={require('./assets/docusaurus-asset-example.docx').default}> Télécharger ce docx </a>

ou

[Télécharger ce docx à l'aide de Markdown](./assets/docusaurus-asset-example.docx)

http://localhost:3000

Télécharger ce docx

Télécharger ce docx en utilisant Markdown

Les liens Markdown sont toujours des chemins de fichiers

Si vous utilisez la syntaxe d'image ou de lien Markdown, tous les chemins de ressources seront résolus comme des chemins de fichiers par Docusaurus et automatiquement convertis en appels à require(). Vous n'avez pas besoin d'utiliser require() dans le Markdown à moins que vous n'utilisiez la syntaxe JSX, que vous devez gérer vous-même.

SVG en ligne

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

Images thématiques

Docusaurus prend en charge les images thématiques : le composant ThemedImage (inclus dans les thèmes) vous permet de basculer la source de l'image en fonction du thème actuel.

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

Images thématiques de style GitHub

GitHub utilise sa propreapproche de thème d'images avec des fragments de chemins, que vous pouvez facilement implémenter vous-même.

Pour basculer la visibilité d'une image à l'aide du fragment de chemin (pour GitHub, il s'agit de #gh-dark-mode-only et #gh-light-mode-only), ajoutez ce qui suit à votre CSS personnalisé (vous pouvez également utiliser votre propre suffixe si vous ne souhaitez pas être relié à 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

Ressources statiques

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. Par exemple, si vous avez configuré les répertoires statiques avec ['public', 'static'], alors pour l'image suivante :

my-doc.md

![Une image depuis static](/img/docusaurus.png)

Docusaurus essayera de le rechercher dans static/img/docusaurus.png et public/img/docusaurus.png. Le lien sera ensuite converti en un appel require() au lieu de rester en tant qu'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.

Si vous avez l'intention d'écrire des URL, vous pouvez utiliser le protocole pathname:// pour désactiver la liaison automatique des ressources.

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

Ce lien sera généré en tant que <img src="/img/docusaurus-asset-example-banner.png" alt="banner" />, sans aucun traitement ou vérification de l'existence de fichiers.