跳到主要内容

资源

有时您希望直接从 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 语法显示图像：

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

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

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
Docusaurus 主题图像Docusaurus 主题图像

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

Docusaurus themed imageDocusaurus themed image

Static assets​

如果 Markdown 链接或图像具有绝对路径，路径将作为文件路径看到，并从静态目录解析。例如，如果您已经配置了 static directories 为 ['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" />，不进行任何处理或文件存在检查。