> For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt.

# Static assets

## Introduction

In Rspress, you may use the following static assets:

- Images, videos and other static assets used in MDX files
- Logo image in the upper-left corner of the site
- Site favicon
- Homepage logo image
- Other static assets

This page explains how to use each kind of static asset.

:::tip Tip

The `docs root` mentioned below refers to the directory specified by the `root` field in `rspress.config.ts`:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  root: 'docs',
});
```

:::

## Static assets used in MDX files

You can import static assets in Markdown or MDX files. Rspress uses [Rsbuild - Static Assets](https://rsbuild.rs/guide/basic/static-assets) under the hood.

### Regular static assets

For example, if the directory structure is as follows:

```tree
docs
├── guide
│   ├── index.mdx
│   └── demo.png
```

If an image is in the same directory as the Markdown file, reference it like this:

```mdx
![](./demo.png)
```

You can also use the `img` tag directly in `.mdx` files:

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

Both usages are transformed into:

```mdx title="index.mdx"
import image from './demo.png';

<img src={image}>
```

You can also import videos, audio files, and other static assets. Other usage patterns follow Rsbuild.

### public folder

The `public` folder under the docs directory stores static assets. These assets are not processed during the build and can be referenced directly by URL.

- When you start the dev server, these assets will be served under the [base](https://rspress.rs/api/config/config-basic.md#base) root path (default `/`).
- When you run a production build, these assets will be copied to the [doc\_build directory](https://rspress.rs/api/config/config-basic.md#outdir).

For example, you can place files like `robots.txt`, `manifest.json`, or `favicon.ico` in the public folder.

Here's an example of placing static assets in the `public` folder. If the root directory is `docs` and the directory structure is as follows:

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

In the above `index.mdx` file, you can use an absolute path to reference `demo.png`:

```mdx
![](/demo.png)
```

When your site is configured with a `base` path and you use an absolute path in an `img` tag, use `normalizeImagePath` from `@rspress/core/runtime` to add the `base` path to `src`:

```tsx title="guide.mdx"
import { normalizeImagePath } from '@rspress/core/runtime';

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

## Upper-left logo

In Rspress, specify the upper-left logo image with the `logo` field. For example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

The `logo` field supports both string and object configurations.

When `logo` is a string, it supports:

- Configured as an **external link**, like the above example.
- Configured as an **absolute path**, such as `/rspress-logo.png`. In this case, Rspress finds `rspress-logo.png` in the `public` folder of your **docs root** and displays it.
- Configured as a **relative path**, such as `./docs/public/rspress-logo.png`. In this case, Rspress resolves `rspress-logo.png` from the project root and displays it.

If your site needs different logos for dark and light mode, use the object form:

```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',
  },
});
```

Here, `light` is the logo path for light mode, and `dark` is the logo path for dark mode. Both values support the same formats as the string form above.

## Favicon

In Rspress, specify the site's favicon with the `icon` field. For example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

The `icon` field supports a string or URL:

- Configured as an **external link**, like the above example.
- Configured as an **absolute path**, such as `/favicon.ico`. In this case, Rspress finds `favicon.ico` in the `public` folder of your **docs root** and displays it.
- Configured as a **relative path**, such as `./docs/public/favicon.ico`. In this case, Rspress resolves `favicon.ico` from the project root and displays it.
- Configured with the `file://` protocol or a `URL`, such as `file:///local_path/favicon.ico`. In this case, Rspress uses the local absolute path `/local_path/favicon.ico` directly.

## Homepage logo

In the homepage [frontmatter configuration](https://rspress.rs/api/config/config-frontmatter.md#hero), specify the homepage logo image with `hero.image.src`. For example:

```mdx title="index.mdx"
---
pageType: home

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

Here, `src` is a string that supports:

- Configured as an **external link**, like the above example.
- Configured as an **absolute path**, such as `/rspress-logo.png`. In this case, Rspress finds `rspress-logo.png` in the `public` folder of your **docs root** and displays it.

## Other static assets

In some scenarios, you may need to deploy specific static assets, such as Netlify's `_headers` file for custom HTTP response headers.

In that case, place these assets directly in the `public` folder under the docs root, such as `docs/public`. During the build, Rspress automatically **copies all assets in the public folder to the output directory**, so they can be deployed with the site.