In general, every website needs assets: images, stylesheets, favicons and 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 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’ll be copied to
This means that if the site's
/, an image in
/static/img/docusaurus_keytar.svg is available at
Referencing your static asset
You can reference assets from the
static folder in your code. You could use hardcoded absolute paths, i.e. starting with a slash /, but remember to include the
baseUrl if it is not
/. However, this will break if you change your
baseUrl in the config.
A better way would be to use the
useBaseUrl utility function which appends the
baseUrl to paths for you.
You can also import SVG images, which will be transformed into React components.
Thanks to MDX, you can also use
useBaseUrl utility function in Markdown files! You'd have to use
<img> tags instead of the Markdown image syntax though. The syntax is exactly the same as in JSX.
You could also just use Markdown image syntax, but you would have to manually maintain the image paths yourself and isn't recommended.
Keep in mind that:
- By default, none of the files in
staticfolder will be post-processed or minified.
- Missing files references 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
.nojekyllfile to your
staticdirectory if you are using GitHub pages for hosting.