资源
有时候你需要在 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 语法显示图像:
![示例横幅](./assets/docusaurus-asset-example-banner.png)
用 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;
}
![Docusaurus 主题图像](/img/docusaurus_keytar.svg#gh-light-mode-only)![Docusaurus 主题图像](/img/docusaurus_speed.svg#gh-dark-mode-only)
静态资源
如果 Markdown 链接或图像使用了绝对路径, 这条路径将被视为一个文件路径,并将从静态目录下解析。 For example, if you have configured
static directories
to be
['public', 'static']
, then for the following image:
![来自静态目录的图像](/img/docusaurus.png)
Docusaurus 将尝试在
static/img/docusaurus.png
和
public/img/docusaurus.png
两 个地方查找它。 链接将随后被转换为
require()
调用,而不是继续作为 URL。 这么做有两个好处:
如果你原意就是写 URL,你可以用
pathname://
协议来禁用自动资源链接的行为。
![横幅](pathname:///img/docusaurus-asset-example-banner.png)
这个链接会被生成为
<img src="/img/docusaurus-asset-example-banner.png" alt="banner" />
, 不会做任何处理,也不会检查文件是否存在。