静态资源处理

介绍

在 Rspress 中，你将有可能使用到如下的静态资源：

• 站点左上角 logo 图片
• 站点 favicon 图标
• 主页 logo 图片
• .md(x) 文件中使用的图片、视频等静态资源
• 其它静态资源

接下来我们将逐个介绍如何使用这些静态资源。

提示

下文提到的 文档根目录 指的是 rspress.config.ts 中的 root 字段指定的目录：

rspress.config.ts

import { defineConfig } from 'rspress/config';
export default defineConfig({
  // 同时支持相对路径和绝对路径
  root: 'docs',
});

左上角 logo

在 Rspress 中，你可以通过 logo 字段来指定左上角的 logo 图片。例如：

rspress.config.ts

import { defineConfig } from 'rspress/config';
export default defineConfig({
  logo: 'https://avatars.githubusercontent.com/u/56892468?s=200&v=4',
});

logo 字段支持字符串和对象两种配置方式。

当 logo 是一个字符串时，有如下的配置情况：

• 配置为外链，如上面的例子。
• 配置为绝对路径，如 /rspress-logo.png，这样 Rspress 在框架内部会自动在你的文档根目录的 public 目录中找到 rspress-logo.png 图片并进行展示。
• 配置为相对路径，如 ./docs/public/rspress-logo.png，这样 Rspress 基于项目根目录寻找到 rspress-logo.png 图片并进行展示。

如果你的网站需要适配暗黑模式，那么也可以使用 logo 的对象配置，如：

rspress.config.ts

import { defineConfig } from 'rspress/config';
export default defineConfig({
  logo: {
    light: 'https://avatars.githubusercontent.com/u/56892468?s=200&v=4',
    dark: 'https://avatars.githubusercontent.com/u/56892468?s=200&v=4',
  },
});

其中，light 代表浅色模式下的 logo 地址，而 dark 代表暗黑模式下的 logo 地址，各自的配置方式和上面的字符串配置一致。

favicon 图标

在 Rspress 中，你可以通过 icon 字段来指定站点的 favicon 图标。例如：

rspress.config.ts

import { defineConfig } from 'rspress/config';
export default defineConfig({
  icon: 'https://avatars.githubusercontent.com/u/56892468?s=200&v=4',
});

icon 字段支持字符串配置，具体配置方式如下：

• 配置为外链，如上面的例子。
• 配置为绝对路径，如 /favicon.ico，这样 Rspress 在框架内部会自动在你的文档根目录的 public 目录中找到 favicon.ico 图标并进行展示。
• 配置为相对路径，如 ./docs/public/favicon.ico，这样 Rspress 基于项目根目录寻找到 favicon.ico 图标并进行展示。

主页 logo

在主页的 frontmatter 配置中，你可以通过 hero.image.src 字段来指定主页的 logo 图片。例如：

index.mdx

---
pageType: home
hero:
  image:
    src: https://avatars.githubusercontent.com/u/56892468?s=200&v=4
    alt: Rspress
---

其中，src 为一个字符串，支持如下的配置方式：

• 配置为外链，如上面的例子。
• 配置为绝对路径，如 /rspress-logo.png，这样 Rspress 在框架内部会自动在你的文档根目录的 public 目录中找到 rspress-logo.png 图片并进行展示。

你可以在 markdown（或 mdx）文件中导入静态资源。相对路径和绝对路径都是支持的，例如，如果在 markdown 同级目录有一张图片，你可以像这样引用它：

.md(x) 中使用的静态资源

![](./demo.png)

当然，在 .mdx 文件中你也可以直接使用 img 标签：

<img src="./demo.png" />

Rspress 将会根据 .mdx 文件路径和图片路径，自动找到图片并响应给浏览器。

另一方面，也可以使用绝对路径导入静态资源。这样，Rspress 将会在文档根目录下的 public 文件夹中寻找资源。

例如，如果根目录是 docs 并且目录结构如下

docs
├── public
│   └── demo.png
├── index.mdx

在如上的 index.mdx 文件中，你可以像这样引用 demo.png：

![](./public/demo.png)

或者用绝对路径来引用：

![](/demo.png)

需要注意的一种特殊情况是，当你的站点配置了 base 路径，那么如果你要使用 img 标签的方式来引入绝对路径，你需要使用 rspress/runtime 提供的 normalizeImagePath 来手动为其 src 添加 base 路径。示例如下：

guide.mdx

import { normalizeImagePath } from 'rspress/runtime';
<img src={normalizeImagePath('/demo.png')} />;

不光是图片，你也可以在 markdown 文件中引入视频、音频等静态资源。

其它静态资源

部分场景下，你可能需要将某些特定的静态资源进行部署，比如添加 Netlify 的部署配置文件 _headers 指定自定义 HTTP 响应头。

那么，你可以直接将这些静态资源放在文档根目录(如 docs)的 public 目录中，Rspress 在项目构建过程中会自动将 public 目录的所有资源拷贝到产物目录。这样，public 下的资源就可以被部署到服务器上了。