跳到主要内容

静态资源

有时你希望直接从 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 的 import 语法。

使用简单的 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()，因为 JSX 语法需要你自己处理路径。

内联 SVG​

道格龙（Docusaurus）开箱即用地支持内联 SVG。

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;
http://localhost:3000

如果你想通过 CSS 修改 SVG 图像的某个部分，这个功能会非常有用。例如，你可以根据当前的主题更改 SVG 的一种颜色。

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg className="themedDocusaurus" />;
/* 亮色模式下，将 SVG 中填充色为 #FFFF50 的部分改为 greenyellow */
[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] {
  fill: greenyellow;
}

/* 暗色模式下，将 SVG 中填充色为 #FFFF50 的部分改为 seagreen */
[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 使用其自己的图片主题化方法，通过路径片段（path fragments）来实现，你可以很容易地自己实现它。

要使用路径片段来切换图片的可见性（对于 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）主题化图片道格龙（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="横幅" />，不会经过任何处理或文件存在性检查。