> For AI agents: the complete documentation index is available at https://rspress.rs/zh/llms.txt, the full documentation bundle is available at https://rspress.rs/zh/llms-full.txt.
# 静态资源处理
## 介绍
在 Rspress 中，你可能会用到以下静态资源：
- MDX 文件中使用的图片、视频等静态资源
- 站点左上角 logo 图片
- 站点 favicon 图标
- 主页 logo 图片
- 其它静态资源
接下来我们将逐个介绍如何使用这些静态资源。
:::tip 提示
下文提到的 `文档根目录` 指的是 `rspress.config.ts` 中的 `root` 字段指定的目录：
```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
export default defineConfig({
// 同时支持相对路径和绝对路径
root: 'docs',
});
```
:::
## MDX 中使用的静态资源
你可以在 `markdown`（或 `mdx`）文件中导入静态资源，Rspress 底层基于 [Rsbuild - 静态资源](https://rsbuild.rs/zh/guide/basic/static-assets) 实现。
### 普通静态资源
例如，目录结构如下：
```tree
docs
├── guide
│ ├── index.mdx
│ └── demo.png
```
如果在 markdown 同级目录有一张图片，你可以像这样引用它：
```mdx
```
当然，在 `.mdx` 文件中你也可以直接使用 img 标签：
```mdx
```
上面两种用法都会被转化为：
```mdx title="index.mdx"
import image from './demo.png';
```
不光是图片，你也可以引入视频、音频等静态资源，使用方式均和 Rsbuild 一致。
### public 目录
docs 目录下的 public 目录可以用于放置一些静态资源，这些资源不会被构建，可以直接通过 URL 引用。
- 当你启动开发服务器时，这些资源会被托管在 [base](https://rspress.rs/zh/api/config/config-basic.md#base) 根路径下（默认 `/`）。
- 当你执行生产模式构建时，这些资源会被拷贝到 [doc\_build 目录](https://rspress.rs/zh/api/config/config-basic.md#outdir)。
比如，你可以在 public 目录下放置 `robots.txt`、`manifest.json` 或 `favicon.ico` 等文件。
下面是一个在 public 目录中放置静态资源的示例，如果根目录是 `docs` 并且目录结构如下：
```tree
docs
├── public
│ └── demo.png
├── index.mdx
```
在如上的 `index.mdx` 文件中，你可以用绝对路径来引用 `demo.png`：
```mdx
```
当你的站点配置了 `base` 路径并且使用 `img` 标签的方式来引入绝对路径，你需要使用 `@rspress/core/runtime` 提供的 `normalizeImagePath` 来手动为其 src 添加 `base` 路径。示例如下：
```tsx title="guide.mdx"
import { normalizeImagePath } from '@rspress/core/runtime';
})
;
```
## 左上角 logo
在 Rspress 中，你可以通过 `logo` 字段来指定左上角的 logo 图片。例如：
```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
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 的对象配置，如：
```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
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 图标。例如：
```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
export default defineConfig({
icon: 'https://avatars.githubusercontent.com/u/56892468?s=200&v=4',
});
```
icon 字段支持字符串或 URL 配置，具体配置方式如下：
- 配置为**外链**，如上面的例子。
- 配置为**绝对路径**，如 `/favicon.ico`，这样 Rspress 在内部会自动在你的**文档根目录**的 `public 目录`中找到 `favicon.ico` 图标并进行展示。
- 配置为**相对路径**，如 `./docs/public/favicon.ico`，这样 Rspress 基于项目根目录寻找到 `favicon.ico` 图标并进行展示。
- 配置为 `file://` 协议或 `URL`，如 `file:///local_path/favicon.ico`，这样 Rspress 直接使用本地绝对路径 `/local_path/favicon.ico` 图标并进行展示。
## 主页 logo
在主页的 [frontmatter 配置](https://rspress.rs/zh/api/config/config-frontmatter.md#hero)中，你可以通过 `hero.image.src` 字段来指定主页的 logo 图片。例如：
```mdx title="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` 图片并进行展示。
## 其它静态资源
部分场景下，你可能需要将某些特定的静态资源进行部署，比如添加 `Netlify` 的部署配置文件 `_headers` 指定自定义 HTTP 响应头。
那么，你可以直接将这些静态资源放在文档根目录(如 `docs`)的 `public` 目录中，Rspress 在项目构建过程中会自动将 public 目录的所有资源**拷贝到产物目录**。这样，public 下的资源就可以被部署到服务器上了。