跳到主要内容
版本:Canary 🚧

资源

有时候你需要在 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 链接到已有的资源,然后把 require 返回的 URL 用于 videoa 链接等地方。

# 我的 Markdown 页面

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

或者

[在 Markdown 里下载这个 docx](./assets/docusaurus-asset-example.docx)
Markdown 链接永远是文件路径

如果你使用了 Markdown 图像或链接语法,所有的资源路径都会被 Docusaurus 解析为文件路径,并自动转换为 require() 调用。 你一般不需要在 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
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 主题图像](/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.pngpublic/img/docusaurus.png 两个地方查找它。 链接将随后被转换为 require() 调用,而不是继续作为 URL。 这么做有两个好处:

  1. 你不必操心 base URL,因为 Docusaurus 会在打包资产时考虑到这一点;
  2. 图像会进入 Webpack 的构建系统,在文件名后多一个散列化的后缀,有助于让浏览器积极缓存图像,提高网站的性能。

如果你原意就是写 URL,你可以用 pathname:// 协议来禁用自动资源链接的行为。

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

这个链接会被生成为 <img src="/img/docusaurus-asset-example-banner.png" alt="banner" />,不会做任何处理,也不会检查文件是否存在。