资源

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

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

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

# 您想要使用的某些资源
/website/docs/assets/docusaurus-asset-example-banner.png
/website/docs/assets/docusaurus-asset-example.docx

图片

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

Markdown 语法

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

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

CommonJS require

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

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

导入语句

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

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

<img src={myImageUrl} alt="示例横幅" />;

以上所有方法都会显示图像：

http://localhost:3000

备注

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

文件

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

# 我的 Markdown 页面

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

或者

[使用 Markdown 下载此 docx](./assets/docusaurus-asset-example.docx)

http://localhost:3000

下载此 docx

使用 Markdown 下载此 docx

Markdown 链接始终是文件路径

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

内联 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 主题图片"
  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 主题图片](/img/docusaurus_keytar.svg#gh-light-mode-only) ![Docusaurus 主题图片](/img/docusaurus_speed.svg#gh-dark-mode-only)

http://localhost:3000

! Docusaurus 主题图片

静态资源

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

my-doc.md

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

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

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

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

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

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