Ressources statiques

Chaque site web a besoin de ressources : images, feuilles de style, icônes etc. Dans de tels cas, vous pouvez créer un répertoire nommé static à la racine de votre projet.

Chaque fichier que vous avez mis dans ce répertoire sera copié à la racine du dossier build généré avec la hiérarchie des répertoires préservée. Par exemple : si vous ajoutez un fichier nommé sun.jpg au dossier statique, il sera copié dans build/sun.jpg.

Cela signifie que :

• pour le site baseUrl : '/', l'image /static/img/docusaurus.png sera servie grâce à /img/docusaurus.png.
• pour le site baseUrl: '/subpath/', l'image /static/img/docusaurus.png sera servie grâce à /subpath/img/docusaurus.png.

Référencement de votre ressource statique

Vous pouvez référencer les ressources du dossier static dans votre code en utilisant des chemins absolus, mais ce n'est pas idéal car changer le baseUrl du site cassera ce lien.

Vous pouvez utiliser import / require() pour la ressource statique (recommandé) ou utilisez la fonction utilitaire useBaseUrl : les deux solutions vont préfixez pour vous baseUrl aux chemins.

Exemple de JSX

MyComponent.js

import DocusaurusImageUrl from '@site/static/img/docusaurus.png';
<img src={DocusaurusImageUrl} />;

MyComponent.js

<img src={require('@site/static/img/docusaurus.png').default} />

MyComponent.js

import useBaseUrl from '@docusaurus/useBaseUrl';
<img src={useBaseUrl('/img/docusaurus.png')} />;

Vous pouvez également importer des fichiers SVG : ils seront transformés en composants React.

MyComponent.js

import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;

Exemple de Markdown

Les liens Markdown et les images faisant référence à des ressources du dossier static seront convertis en require("@site/static/assetName.png")", et la baseUrl du site sera automatiquement ajoutée pour vous comme préfixe.

my-doc.md

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

Grâce à MDX, vous pouvez également utiliser la fonction utilitaire useBaseUrl dans les fichiers Markdown ! Vous devriez cependant utiliser des balises html comme <img> au lieu de la syntaxe de l'image Markdown. La syntaxe est exactement la même qu'en JSX.

my-doc.mdx

---id: my-doctitle: My Doc---
// Ajouter en haut du fichier, sous la première partie.import useBaseUrl from '@docusaurus/useBaseUrl';
...
<img alt="Docusaurus with Keytar" src={useBaseUrl('/img/docusaurus_keytar.svg')} />

Mises en garde

Gardez à l'esprit que :

• Par défaut, aucun des fichiers du dossier static ne sera post-traité, haché ou minifié.
• Les fichiers manquants référencés via des chemins absolus codés en dur ne seront pas détectés au moment de la compilation, et entraîneront une erreur 404.
• Par défaut, les pages GitHub exécutent les fichiers publiés via Jekyll. Puisque Jekyll va se débarrasser de tous les fichiers qui commencent par _, il est recommandé de désactiver Jekyll en ajoutant un fichier vide nommé .nojekyll dans votre répertoire static si vous utilisez les pages GitHub pour l'hébergement.