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. Every file you put into that directory will be copied into the root of the generated build folder with the directory hierarchy preserved. E.g. if you add a file named sun.jpg to the static folder, it will be copied to build/sun.jpg.

This means that:

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

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

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 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:

You can also import SVG files: they will be transformed into React components.

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.

Docusaurus will only parse links that are in Markdown syntax. If your asset references are using the JSX tag / , nothing will be done.

In CSS, the url() function is commonly used to reference assets like fonts and images. To reference a static asset, use absolute paths:

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

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:

Keep in mind that: