在 Rspress 中,你将有可能使用到如下的静态资源:
接下来我们将逐个介绍如何使用这些静态资源。
下文提到的 文档根目录
指的是 rspress.config.ts
中的 root
字段指定的目录:
在 Rspress 中,你可以通过 logo
字段来指定左上角的 logo 图片。例如:
logo 字段支持字符串和对象两种配置方式。
当 logo 是一个字符串时,有如下的配置情况:
/rspress-logo.png
,这样 Rspress 在框架内部会自动在你的文档根目录的 public 目录
中找到 rspress-logo.png
图片并进行展示。./docs/public/rspress-logo.png
,这样 Rspress 基于项目根目录寻找到 rspress-logo.png
图片并进行展示。如果你的网站需要适配暗黑模式,那么也可以使用 logo 的对象配置,如:
其中,light
代表浅色模式下的 logo 地址,而 dark
代表暗黑模式下的 logo 地址,各自的配置方式和上面的字符串配置一致。
在 Rspress 中,你可以通过 icon
字段来指定站点的 favicon 图标。例如:
icon 字段支持字符串配置,具体配置方式如下:
/favicon.ico
,这样 Rspress 在框架内部会自动在你的文档根目录的 public 目录
中找到 favicon.ico
图标并进行展示。./docs/public/favicon.ico
,这样 Rspress 基于项目根目录寻找到 favicon.ico
图标并进行展示。在主页的 frontmatter 配置中,你可以通过 hero.image.src
字段来指定主页的 logo 图片。例如:
其中,src 为一个字符串,支持如下的配置方式:
/rspress-logo.png
,这样 Rspress 在框架内部会自动在你的文档根目录的 public 目录
中找到 rspress-logo.png
图片并进行展示。你可以在 markdown
(或 mdx
)文件中导入静态资源。相对路径和绝对路径都是支持的,例如,如果在 markdown 同级目录有一张图片,你可以像这样引用它:
.md(x)
中使用的静态资源当然,在 .mdx
文件中你也可以直接使用 img 标签:
Rspress 将会根据 .mdx
文件路径和图片路径,自动找到图片并响应给浏览器。
另一方面,也可以使用绝对路径导入静态资源。这样,Rspress 将会在文档根目录
下的 public
文件夹中寻找资源。
例如,如果根目录是 docs
并且目录结构如下
在如上的 index.mdx
文件中,你可以像这样引用 demo.png
:
或者用绝对路径来引用:
需要注意的一种特殊情况是,当你的站点配置了 base
路径,那么如果你要使用 img
标签的方式来引入绝对路径,你需要使用 rspress/runtime
提供的 normalizeImagePath
来手动为其 src 添加 base
路径。示例如下:
不光是图片,你也可以在 markdown 文件中引入视频、音频等静态资源。
部分场景下,你可能需要将某些特定的静态资源进行部署,比如添加 Netlify
的部署配置文件 _headers
指定自定义 HTTP 响应头。
那么,你可以直接将这些静态资源放在文档根目录(如 docs
)的 public
目录中,Rspress 在项目构建过程中会自动将 public 目录的所有资源拷贝到产物目录。这样,public 下的资源就可以被部署到服务器上了。