mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-28 17:57:48 +02:00
45f1a669b5
Co-authored-by: Joshua Chen <sidachen2003@gmail.com> Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
109 lines
4.9 KiB
Text
109 lines
4.9 KiB
Text
---
|
|
description: Static assets are the non-code files that are directly copied to the build output. Learn about how they are handled and what the best practices of using static assets are.
|
|
---
|
|
|
|
# Static Assets
|
|
|
|
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:
|
|
|
|
- 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:
|
|
|
|
```js title="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.
|
|
|
|
## Referencing your static asset {#referencing-your-static-asset}
|
|
|
|
### In JSX {#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:
|
|
|
|
```jsx title="MyComponent.js"
|
|
import DocusaurusImageUrl from '@site/static/img/docusaurus.png';
|
|
|
|
<img src={DocusaurusImageUrl} />;
|
|
```
|
|
|
|
```jsx title="MyComponent.js"
|
|
<img src={require('@site/static/img/docusaurus.png').default} />
|
|
```
|
|
|
|
```jsx title="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.
|
|
|
|
```jsx title="MyComponent.js"
|
|
import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
|
|
|
|
<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;
|
|
```
|
|
|
|
### In Markdown {#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](./guides/markdown-features/markdown-features-assets.mdx).
|
|
|
|
```md
|
|
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>
|
|
```
|
|
|
|
:::warning 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}
|
|
|
|
In CSS, the `url()` function is commonly used to reference assets like fonts and images. To reference a static asset, use absolute paths:
|
|
|
|
```css
|
|
@font-face {
|
|
font-family: 'Caroline';
|
|
src: url('/font/Caroline.otf');
|
|
}
|
|
```
|
|
|
|
The `static/font/Caroline.otf` asset will be loaded by the bundler.
|
|
|
|
:::warning 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.
|
|
|
|
:::
|
|
|
|
## Caveats {#caveats}
|
|
|
|
Keep in mind that:
|
|
|
|
- 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.
|
|
- By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.com/). 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.
|