Ressources statiques

Les ressources statiques sont les fichiers non codés qui sont directement copiés dans le résultat de la construction. Elles incluent des images, des feuilles de style, des favicons, des polices, etc.

By default, you are suggested to put these assets in the static folder. Every file you put into that directory will be copied into the root of the generated build folder with the directory hierarchy preserved. Par exemple : if you add a file named sun.jpg to the static folder, it will be copied to build/sun.jpg.

Cela signifie que :

• for site baseUrl: '/', the image /static/img/docusaurus.png will be served at /img/docusaurus.png.
• for site baseUrl: '/subpath/', the image /static/img/docusaurus.png will be served at /subpath/img/docusaurus.png.

You can customize the static directory sources in docusaurus.config.js. For example, we can add public as another possible path:

docusaurus.config.js

module.exports = {
  title: 'My site',
  staticDirectories: ['public', 'static'],
  // ...
};

Now, all files in public as well as static will be copied to the build output.

Referencing your static asset

In JSX

In JSX, you can reference assets from the static folder in your code using absolute URLs, but this is not ideal because changing the site baseUrl will break those links. For the image <img src="/img/docusaurus.png" /> served at https://example.com/test, the browser will try to resolve it from the URL root, i.e. as https://example.com/img/docusaurus.png, which will fail because it's actually served at https://example.com/test/img/docusaurus.png.

You can import() or require() the static asset (recommended), or use the useBaseUrl utility function: both prepend the baseUrl to paths for you.

Exemples :

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" />;

In Markdown

In Markdown, you can stick to using absolute paths when writing links or images in Markdown syntax because Docusaurus handles them as require calls instead of URLs when parsing the Markdown. See Markdown static assets.

You write a link like this: [Download this document](/files/note.docx)

Docusaurus changes that to: <a href={require('static/files/note.docx')}>Download this document</a>

use Markdown syntax

Docusaurus n'analysera que les liens qui sont dans la syntaxe Markdown. If your asset references are using the JSX tag <a> / <img>, nothing will be done.

In CSS

In CSS, the url() function is commonly used to reference assets like fonts and images. Pour référencer une ressource statique, utilisez des chemins absolus :

@font-face {
  font-family: 'Caroline';
  src: url('/font/Caroline.otf');
}

The static/font/Caroline.otf asset will be loaded by the bundler.

important takeaway

One important takeaway: never hardcode your base URL! The base URL is considered an implementation detail and should be easily changeable. Tous les chemins, même lorsqu'ils ressemblent à des slugs d'URL, sont en fait des chemins de fichier.

Si le modèle mental des slugs d'URL vous paraît plus compréhensible, voici une règle générale :

• Pretend you have a base URL like /test/ when writing JSX so you don't use an absolute URL path like src="/img/thumbnail.png" but instead require the asset.
• Pretend it's / when writing Markdown or CSS so you always use absolute paths without the base URL.

Caveats

Gardez à l'esprit que :

• By default, none of the files in the static folder will be post-processed, hashed, or minified.
  • However, as we've demonstrated above, we are usually able to convert them to require calls for you so they do get processed. C'est une bonne chose pour une mise en cache agressive et une meilleure expérience utilisateur.
• 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.
• By default, GitHub Pages runs published files through Jekyll. Since Jekyll will discard any files that begin with _, it is recommended that you disable Jekyll by adding an empty file named .nojekyll file to your static directory if you are using GitHub pages for hosting.