Arquivos estáticos

Static assets are the non-code files that are directly copied to the build output. They include images, stylesheets, favicons, fonts, etc.

By default, you are suggested to put these assets in the static folder. Cada arquivo que você colocar dentro esse diretório será copiado na raiz da pasta de compilação gerada com a hierarquia de diretório preservada. Ex. se você adicionar um arquivo chamado sun.jpg na pasta estática, ele será copiado para build/sun.jpg.

Isto significa que:

• para o site baseUrl: '/', a imagem /static/img/docusaurus.png será exibida em /img/docusaurus.png.
• para o site baseUrl: '/subpath/', a imagem /static/img/docusaurus.png será exibida em /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

export default {
  title: 'My site',
  staticDirectories: ['public', 'static'],
  // ...
};

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

Referenciando seu arquivo estático

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.

Examples:

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')} />;

Você também pode importar arquivos SVG: eles serão transformados em componentes 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 will only parse links that are in Markdown syntax. 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. To reference a static asset, use absolute paths:

@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. All paths, even when they look like URL slugs, are actually file paths.

If you find the URL slug mental model more understandable, here's a rule of thumb:

• 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.

Ressalvas

Tenha em mente 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. This is good for aggressive caching and better user experience.
• Missing files referenced via hard-coded absolute paths will not be detected at compilation time and will result in a 404 error.
• Por padrão, o GitHub Pages executa arquivos publicados através do Jekyll. Uma vez que o Jekyll irá descartar quaisquer arquivos que comecem com _, é recomendável que você desative o Jekyll adicionando um arquivo vazio chamado .nojekyll para o seu diretório static se você estiver usando páginas do GitHub para hospedagem.