close
Rspress
  • 中文

      • 静态资源处理

      介绍

      在 Rspress 中，你可能会用到以下静态资源：

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

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

      提示

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

      rspress.config.ts
      import { defineConfig } from '@rspress/core';

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

      MDX 中使用的静态资源

      你可以在 markdown（或 mdx）文件中导入静态资源，Rspress 底层基于 Rsbuild - 静态资源 实现。

      普通静态资源

      例如，目录结构如下：

      docs
      guide
      index.mdx
      demo.png

      如果在 markdown 同级目录有一张图片，你可以像这样引用它：

      ![](./demo.png)

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

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

      上面两种用法都会被转化为：

      index.mdx
      import image from './demo.png';

<img src={image}>

      不光是图片，你也可以引入视频、音频等静态资源，使用方式均和 Rsbuild 一致。

      public 目录

      docs 目录下的 public 目录可以用于放置一些静态资源，这些资源不会被构建，可以直接通过 URL 引用。

      • 当你启动开发服务器时，这些资源会被托管在 base 根路径下（默认 /）。
      • 当你执行生产模式构建时，这些资源会被拷贝到 doc_build 目录。

      比如，你可以在 public 目录下放置 robots.txt、manifest.json 或 favicon.ico 等文件。

      下面是一个在 public 目录中放置静态资源的示例，如果根目录是 docs 并且目录结构如下：

      docs
      public
      demo.png
      index.mdx

      在如上的 index.mdx 文件中，你可以用绝对路径来引用 demo.png：

      ![](/demo.png)

      当你的站点配置了 base 路径并且使用 img 标签的方式来引入绝对路径，你需要使用 @rspress/core/runtime 提供的 normalizeImagePath 来手动为其 src 添加 base 路径。示例如下：

      guide.mdx
      import { normalizeImagePath } from '@rspress/core/runtime';

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

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

      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 的对象配置，如：

      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 图标。例如：

      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 图标并进行展示。

      在主页的 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 图片并进行展示。

      其它静态资源

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

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