跳转至主内容
Version: 2.0.0-alpha.74

静态资源

每个网站都需要静态资源:图像、样式表、图标等等。 您可以在项目根目录创建 static 文件夹来处理静态文件。

放入此文件夹中的每个文件将自动复制进生成的 build 文件夹的根目录,同时保留其目录结构。 举个例子, 若您向 static 文件夹添加了 sun.jpg 文件,则其将会被复制到 build/sun.jpg 下。

这意味着:

  • 若设置 baseUrl: '/',则图像 /static/img/docusaurus.png 将位于 /img/docusaurus.png 处;
  • 若设置 baseUrl: '/子目录/',则图像 /static/img/docusaurus.png 将位于 /子目录/img/docusaurus.png 处。

引用您的静态资源#

您可以在代码中使用绝对路径来引用 static 文件夹中的静态资源。但我们不推荐您这么做,因为修改 baseUrl使得这些链接失效

我们推荐您 import / require() 静态资源,或使用 useBaseUrl 工具函数:两者都能为您在网址前加上 baseUrl

JSX 示例#

MyComponent.js
import DocusaurusImageUrl from '@site/static/img/docusaurus.png';
<img src={DocusaurusImageUrl} />;
MyComponent.js
<img src={require('@site/static/img/docusaurus.png').default} />
MyComponent.js
import useBaseUrl from '@docusaurus/useBaseUrl';
<img src={useBaseUrl('/img/docusaurus.png')} />;

您也可以导入 SVG 文件,其将被自动转换至 React 组件。

MyComponent.js
import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;

Markdown 示例#

引用 static 文件夹中的 Markdown 链接及图像将自动转换为 require("@site/static/assetName.png")" 格式,Docusaurus 会为您自动在网址前加上 baseUrl 变量

my-doc.md
![Docusaurus](/img/docusaurus.png)

得益于 MDX,您也可以在 Markdown 文件中使用 useBaseUrl 工具函数! 但是,您需要使用类似 <img> 的 HTML 标签而非 Markdown 图像标签。 其语法与 JSX 一致。

my-doc.mdx
---id: my-doctitle: 我的文档---
// 添加到文件顶部,前言下方import useBaseUrl from '@docusaurus/useBaseUrl';
...
<img alt="Docusaurus 与 Keytar" src={useBaseUrl('/img/docusaurus_keytar.svg')} />

提醒#

有几点需要留意:

  • 默认情况下,static 内的文件都不会被后处理、散列或精简;
  • 使用硬编码的绝对路径引用的缺失文件无法在编译时被检测到,这会导致 404 错误;
  • 默认情况下,GitHub Pages 通过 Jekyll 运行已发布的文件。 由于 Jekyll 忽略任意以 _ 开头的文件,所以若您使用 GitHub Pages,我们推荐您在 static 文件夹中新建 .nojekyll 文件来禁用 Jekyll。