资源

¥Assets

有时你想直接从 Markdown 文件链接到资源（例如 docx 文件、图片...），并且使用它可以方便地将资源与 Markdown 文件共置。

¥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.

让我们想象一下以下文件结构：

¥Let's imagine the following file structure:

# Your doc
/website/docs/myFeature.mdx

# Some assets you want to use
/website/docs/assets/docusaurus-asset-example-banner.png
/website/docs/assets/docusaurus-asset-example.docx

图片

¥Images

你可以通过三种不同的方式显示图片：Markdown 语法、CJS require 或 ES 导入语法。

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

Markdown syntax

使用简单的 Markdown 语法显示图片：

¥Display images using simple Markdown syntax:

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

CommonJS require

在 JSX 图片标签中使用内联 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

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

¥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" />;

以上所有结果都会显示图片：

¥All of the above result in displaying the image:

http://localhost:3000

注意

如果你使用的是 @docusaurus/plugin-ideal-image，则需要使用专用图片组件，如文档所述。

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

文件

¥Files

同样，你可以通过 require 并在 video、a 锚链接等中使用返回的 URL 来链接到现有资源。

¥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 链接始终是文件路径

如果你使用 Markdown 图片或链接语法，所有资源路径都将被 Docusaurus 解析为文件路径，并自动转换为 require() 调用。除非你使用 JSX 语法，否则你不需要在 Markdown 中使用 require()，而你必须自己处理该语法。

¥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.

内联 SVG

¥Inline SVGs

Docusaurus 支持开箱即用的内联 SVG。

¥Docusaurus supports inlining SVGs out of the box.

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;

http://localhost:3000

如果你想通过 CSS 更改 SVG 图片的一部分，这会很有用。例如，你可以根据当前主题更改 SVG 颜色之一。

¥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

主题图片

¥Themed Images

Docusaurus 支持主题图片：ThemedImage 组件（包含在主题中）允许你根据当前主题切换图片源。

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

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 风格的主题图片

¥GitHub-style themed images

GitHub 使用自己的 图片主题化方法 和路径片段，你可以轻松地自己实现。

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

要使用路径片段（对于 GitHub，为 #gh-dark-mode-only 和 #gh-light-mode-only）切换图片的可见性，请将以下内容添加到自定义 CSS（如果你不想耦合到 GitHub，也可以使用自己的后缀）：

¥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

如果 Markdown 链接或图片具有绝对路径，则该路径将被视为文件路径，并将从静态目录解析。例如，如果你将 静态目录 配置为 ['public', 'static']，则如下图：

¥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 将尝试在 static/img/docusaurus.png 和 public/img/docusaurus.png 中寻找它。然后，该链接将转换为 require() 调用，而不是保留为 URL。这在两个方面是可取的：

¥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. 你不必担心基本 URL，Docusaurus 将在提供资源时处理该 URL；

   ¥You don't have to worry about the base URL, which Docusaurus will take care of when serving the asset;

2. 图片进入 Webpack 的构建管道，其名称将附加一个哈希值，这使浏览器能够主动缓存图片并提高站点的性能。

   ¥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.

如果你打算编写 URL，则可以使用 pathname:// 协议禁用自动资源链接。

¥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)

该链接将生成为 <img src="/img/docusaurus-asset-example-banner.png" alt="banner" />，不进行任何处理或文件存在检查。

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