资源

Sometimes you want to link to assets (e.g. docx files, images...) directly from Markdown files, and it is convenient to co-locate the asset next to the Markdown file using it.

请思考如下文件结构：

# 你的文档
/website/docs/myFeature.mdx

# 你想用的一些静态资源
/website/docs/assets/docusaurus-asset-example-banner.png
/website/docs/assets/docusaurus-asset-example.docx

Images

你可以用三种不同的方式展示图像：Markdown 语法、CJS require、ES import 语法。

Markdown syntax

用简单的 Markdown 语法显示图像：

![示例横幅](./assets/docusaurus-asset-example-banner.png)

CommonJS require

Display images using inline CommonJS require in JSX image tag:

<img
  src={require('./assets/docusaurus-asset-example-banner.png').default}
  alt="Example banner"
/>

Import statement

Display images using ES import syntax and JSX image tag:

import myImageUrl from './assets/docusaurus-asset-example-banner.png';

<img src={myImageUrl} alt="Example banner" />;

上述所有方法最后都会显示这样的图像：

http://localhost:3000

备注

If you are using @docusaurus/plugin-ideal-image, you need to use the dedicated image component, as documented.

Files

In the same way, you can link to existing assets by require'ing them and using the returned URL in videos, a anchor links, etc.

# My Markdown page

<a target="\_blank" href={require('./assets/docusaurus-asset-example.docx').default}> Download this docx </a>

or

[Download this docx using Markdown](./assets/docusaurus-asset-example.docx)

http://localhost:3000

Download this docx

Download this docx using Markdown

Markdown links are always file paths

If you use the Markdown image or link syntax, all asset paths will be resolved as file paths by Docusaurus and automatically converted to require() calls. You don't need to use require() in Markdown unless you use the JSX syntax, which you do have to handle yourself.

Inline SVGs

Docusaurus 原生支持内嵌 SVG。

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;

http://localhost:3000

这在你需要通过 CSS 调整 SVG 图片中的某些部分时会很有用。 举个例子，你可以基于当前主题更改 SVG 的颜色。

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg className="themedDocusaurus" />;

[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] {
  fill: greenyellow;
}

[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
  fill: seagreen;
}

http://localhost:3000

Themed Images

Docusaurus supports themed images: the ThemedImage component (included in the themes) allows you to switch the image source based on the current theme.

import ThemedImage from '@theme/ThemedImage';

<ThemedImage
  alt="Docusaurus themed image"
  sources={{
    light: useBaseUrl('/img/docusaurus_light.svg'),
    dark: useBaseUrl('/img/docusaurus_dark.svg'),
  }}
/>;

http://localhost:3000

GitHub-style themed images

GitHub uses its own image theming approach with path fragments, which you can easily implement yourself.

To toggle the visibility of an image using the path fragment (for GitHub, it's #gh-dark-mode-only and #gh-light-mode-only), add the following to your custom CSS (you can also use your own suffix if you don't want to be coupled to GitHub):

src/css/custom.css

[data-theme='light'] img[src$='#gh-dark-mode-only'],
[data-theme='dark'] img[src$='#gh-light-mode-only'] {
  display: none;
}

![Docusaurus 主题图像](/img/docusaurus_keytar.svg#gh-light-mode-only)![Docusaurus 主题图像](/img/docusaurus_speed.svg#gh-dark-mode-only)

http://localhost:3000

Static assets

如果 Markdown 链接或图像使用了绝对路径， 这条路径将被视为一个文件路径，并将从静态目录下解析。 For example, if you have configured static directories to be ['public', 'static'], then for the following image:

my-doc.md

![来自静态目录的图像](/img/docusaurus.png)

Docusaurus will try to look for it in both static/img/docusaurus.png and public/img/docusaurus.png. The link will then be converted to a require() call instead of staying as a URL. 这么做有两个好处：

1. 你不必操心 base URL，因为 Docusaurus 会在打包资产时考虑到这一点；
2. 图像会进入 Webpack 的构建系统，在文件名后多一个散列化的后缀，有助于让浏览器积极缓存图像，提高网站的性能。

If you intend to write URLs, you can use the pathname:// protocol to disable automatic asset linking.

![横幅](pathname:///img/docusaurus-asset-example-banner.png)

This link will be generated as <img src="/img/docusaurus-asset-example-banner.png" alt="banner" />, without any processing or file existence checking.