资源

有时您希望直接从 Markdown 文件链接到资源（例如 docx 文件、图像等），并且将资源与使用它的 Markdown 文件放在一起非常方便。

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

# 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

图像

您可以通过三种不同的方式显示图像：Markdown 语法、CJS require 或 ES import 语法。

Markdown 语法

使用简单的 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"
/>

导入语句

使用 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，则需要使用专用的图像组件，如文档中所述。

文件

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

# 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

下载此 docx

使用 Markdown 下载此 docx

Markdown 链接始终是文件路径

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

内联 SVG

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

主题图像

Docusaurus 支持主题图像：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 样式的主题图像

GitHub 使用其自己的 图像主题方法（使用路径片段），您可以轻松地自己实现它。

要使用路径片段切换图像的可见性（对于 GitHub，它是 #gh-dark-mode-only 和 #gh-light-mode-only），请将以下内容添加到您的自定义 CSS 中（如果您不想与 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

静态资源

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

my-doc.md

![An image from the static](/img/docusaurus.png)

Docusaurus 将尝试在 static/img/docusaurus.png 和 public/img/docusaurus.png 中查找它。然后，链接将转换为 require() 调用，而不是保留为 URL。这在两个方面是可取的

1. 您不必担心基本 URL，Docusaurus 会在提供资源时处理它；
2. 该图像进入 Webpack 的构建管道，并且其名称将附加哈希值，这使浏览器能够积极地缓存图像并提高您网站的性能。

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

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

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