mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-03 08:49:51 +02:00
docs(v2): improve static assets docs (#1822)
* docs(v2): improve static assets docs * docs(v2): improve static assets docs
This commit is contained in:
parent
1c5a6ee244
commit
e3f25b2a45
1 changed files with 38 additions and 19 deletions
|
@ -5,38 +5,57 @@ title: Static Assets
|
|||
|
||||
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 `build/sun.jpg`.
|
||||
|
||||
This means that if the site's `baseUrl` is `/`, an image in `/static/img/docusaurus_keytar.svg` is available at `<baseUrl>/docusaurus_keytar.svg`.
|
||||
This means that if the site's `baseUrl` is `/`, an image in `/static/img/docusaurus_keytar.svg` is available at `/img/docusaurus_keytar.svg`.
|
||||
|
||||
<!-- TODO: Yangshun: This is inaccurate for sites with a non '/' baseUrl -->
|
||||
|
||||
## Referencing your static asset
|
||||
|
||||
You can reference assets from the static folder in your code with absolute path, i.e. starting with a slash /.
|
||||
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.
|
||||
|
||||
### Markdown example
|
||||
|
||||
```markdown
|
||||
<!-- reference static/img/docusaurus.png -->
|
||||
|
||||

|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||

|
||||
A better way would be to use the `withBaseUrl` utility function which appends the `baseUrl` to paths for you.
|
||||
|
||||
### JSX example
|
||||
|
||||
```jsx
|
||||
// reference static/img/slash-birth.png
|
||||
<img src="/img/slash-birth.png" alt="docusaurus mascot" />
|
||||
// MyComponent.js
|
||||
import withBaseUrl from '@docusaurus/withBaseUrl';
|
||||
|
||||
<img
|
||||
alt="Docusaurus with Keytar"
|
||||
src={withBaseUrl('img/docusaurus_keytar.svg')}
|
||||
/>;
|
||||
```
|
||||
|
||||
Result:
|
||||
### Markdown example
|
||||
|
||||
<img src="/img/slash-birth.png" alt="docusaurus mascot" />
|
||||
Thanks to MDX, you can also use `withBaseUrl` 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.
|
||||
|
||||
```txt
|
||||
// my-doc.mdx
|
||||
---
|
||||
id: my-doc
|
||||
title: My Doc
|
||||
---
|
||||
|
||||
import withBaseUrl from '@docusaurus/withBaseUrl'; // Add to the top of the file below the front matter.
|
||||
|
||||
...
|
||||
|
||||
<img alt="Docusaurus with Keytar" src={withBaseUrl('img/docusaurus_keytar.svg')} />;
|
||||
```
|
||||
|
||||
You could also just use Markdown image syntax, but you would have to manually maintain the image paths yourself and isn't recommended.
|
||||
|
||||
```md
|
||||
// my-doc.md
|
||||
|
||||

|
||||
```
|
||||
|
||||
### Caveats
|
||||
|
||||
Keep in mind that:
|
||||
|
||||
- None of the files in static folder will be post-processed or minified.
|
||||
- Missing files will not be called at compilation time, and will result in a 404 error.
|
||||
- By default, none of the files in `static` folder 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.
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue