资源
有时候你需要在 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 语法
- CommonJS require
- import 语句
用简单的 Markdown 语法显示图像:

用 JSX img 标签及行内 CommonJS require
显示图像:
<img
src={require('./assets/docusaurus-asset-example-banner.png').default}
alt="示例横幅"
/>
用 JSX img 标签和 ES import
语法显示图像:
import myImageUrl from './assets/docusaurus-asset-example-banner.png';
<img src={myImageUrl} alt="示例横幅" />;
上述所有方法最后都会显示这样的图像:
If you are using @docusaurus/plugin-ideal-image, you need to use the dedicated image component, as documented.
文件
同样地, 你可以通过 require
链接到已有的资源,然后把 require 返回的 URL 用于 video
、a
链接等地方。
# 我的 Markdown 页面
<a target="\_blank" href={require('./assets/docusaurus-asset-example.docx').default}> 下载这个 docx </a>
或者
[在 Markdown 里下载这个 docx](./assets/docusaurus-asset-example.docx)
如果你使用了 Markdown 图像或链接语法,所有的资源路径都会被 Docusaurus 解析为文件路径,并自动转换为 require()
调用。 你一般不需要在 Markdown 中使用 require()
,除非你使用了 JSX 语法——这时候就确实需要你自己处理了。
内联 SVG
Docusaurus 原生支持内嵌 SVG。
import DocusaurusSvg from './docusaurus.svg';
<DocusaurusSvg />;
这在你需要通过 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;
}
主题化图像
Docusaurus 支持主题化图像:主题自带的 ThemedImage
组件允许你根据当前主题切换图像源。
import ThemedImage from '@theme/ThemedImage';
<ThemedImage
alt="Docusaurus 主 题化图像"
sources={{
light: useBaseUrl('/img/docusaurus_light.svg'),
dark: useBaseUrl('/img/docusaurus_dark.svg'),
}}
/>;
GitHub 式的主题图像
GitHub 有它自己的图像主题化方法,是通过路径片段实现的,你可以轻松地自行实现。
要使用路径片段切换图片是否可见(GitHub 用的是 #gh-dark-mode-only
和 #gh-light-mode-only
),你需要添加以下内容到你的自定义 CSS(如果你不想和 GitHub 相耦合,你也可以用你自己的路径后缀):
[data-theme='light'] img[src$='#gh-dark-mode-only'],
[data-theme='dark'] img[src$='#gh-light-mode-only'] {
display: none;
}
