静态资源（Assets）

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

图片

You can display images in three different ways: Markdown syntax, CJS require, or ES imports syntax.

Markdown syntax

纯粹使用 Markdown 语法来显示图片：

![Example banner](./assets/docusaurus-asset-example-banner.png)

CommonJS require

在 JSX 图片标签中使用内联的 CommonJS 的 require 语法来显示图片：

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

Import statement

使用 ES 的 import 语法和 JSX 的图片标签来显示图片：

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

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

上述所有方式都将显示如下所示图片：

http://localhost:3000

备注

如果你使用了 @docusaurus/plugin-ideal-image 插件，则需要使用专用的图片组件，请参考相应的文档。

其他类型的文件

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>

或者

[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

This can be useful if you want to alter the part of the SVG image via CSS. For example, you can change one of the SVG colors based on the current theme.

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

主题图片

Docusaurus 支持主题图片（themed images）：ThemedImage 组件（已包含在主题中）可以让你根据当前所使用的主题切换图片。

import useBaseUrl from '@docusaurus/useBaseUrl';
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 themed image](/img/docusaurus_keytar.svg#gh-light-mode-only)![Docusaurus themed image](/img/docusaurus_speed.svg#gh-dark-mode-only)

http://localhost:3000

Static assets

If a Markdown link or image has an absolute path, the path will be seen as a file path and will be resolved from the static directories. For example, if you have configured static directories to be ['public', 'static'], then for the following image:

my-doc.md

![An image from the static](/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. This is desirable in two regards:

1. You don't have to worry about the base URL, which Docusaurus will take care of when serving the asset;
2. The image enters Webpack's build pipeline and its name will be appended by a hash, which enables browsers to aggressively cache the image and improves your site's performance.

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

![banner](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.