Skip to main content
Version: 2.0.0-beta.9 🚧

Static Assets

Every website needs assets: images, stylesheets, favicons etc. In such cases, you can create a directory named static at the root of your project.

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:

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

Referencing your static asset

You can reference assets from the static folder in your code using absolute paths, but this is not ideal because changing the site baseUrl will break those links.

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

JSX example

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

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

MyComponent.js
import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';

<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;

Markdown example

Markdown links and images referencing assets of the static folder will be converted to require("@site/static/assetName.png")", and the site baseUrl will be automatically prepended for you.

my-doc.md
![Docusaurus](/img/docusaurus.png)

Thanks to MDX, you can also use useBaseUrl utility function in Markdown files! You'd have to use html tags like <img> instead of the Markdown image syntax though. The syntax is exactly the same as in JSX.

my-doc.mdx
---
id: my-doc
title: My Doc
---

// Add to the top of the file below the front matter.
import useBaseUrl from '@docusaurus/useBaseUrl';

...

<img alt="Docusaurus with Keytar" src={useBaseUrl('/img/docusaurus_keytar.svg')} />

Caveats

Keep in mind that:

  • By default, none of the files in static folder will be post-processed, hashed or minified.
  • Missing files referenced via hardcoded absolute paths will not be detected at compilation time, and will result in a 404 error.
  • 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.