Theme config

Theme config is located under themeConfig in the doc param. For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    // ...
  },
});

nav

Type: Array
Default: []

The nav configuration is an array of NavItem with the following types:

interface NavItem {
  // Navbar text
  text: string;
  // Navbar link
  link: '/';
  // Whether it is a download link
  download?: boolean;
  // Activation rules for navbar links
  activeMatch: '^/$|^/';
  // svg tag string or image URL(optional)
  tag?: string;
}

activeMatch is used to match the current route, when the route matches the activeMatch rule, the nav item will be highlighted. By default, activeMatch is the link of the nav item.

For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Home',
        link: '/',
      },
      {
        text: 'Guide',
        link: '/guide/',
      },
    ],
  },
});

Of course, multi-level menus can also be configured in the nav array with the following types:

interface NavGroup {
  text: string;
  // submenu
  items: NavItem[];
  // svg tag string or image URL(optional)
  tag?: string;
}

For example the following configuration:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Home',
        link: '/',
      },
      {
        text: 'Guide',
        items: [
          {
            text: 'Getting Started',
            link: '/guide/getting-started',
          },
          {
            text: 'Advanced',
            link: '/guide/advanced',
          },
          // Also support sub group menu
          {
            text: 'Group',
            items: [
              {
                text: 'Personal',
                link: 'http://example.com/',
              },
              {
                text: 'Company',
                link: 'http://example.com/',
              },
            ],
          },
        ],
      },
    ],
  },
});

Type: Object

The sidebar of the website. The config is an object with the following types:

// The key is the path of SidebarGroup
// value is an array of SidebarGroup
type Sidebar = Record<string, SidebarGroup[]>;

interface SidebarGroup {
  text: string;
  link?: string;
  items: SidebarItem[];
  // whether to be collapsible
  collapsible?: boolean;
  // Whether to be collapsed by default
  collapsed?: boolean;
  // svg tag string or image URL(optional)
  tag?: string;
}

type SidebarItem = {
  // sidebar text
  text: string;
  // sidebar link
  link: string;
  // svg tag string or image URL(optional)
  tag?: string;
};

For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            {
              text: 'Introduction',
              link: '/guide/getting-started/introduction',
            },
            {
              text: 'Installation',
              link: '/guide/getting-started/installation',
            },
          ],
        },
        {
          text: 'Advanced',
          items: [
            {
              text: 'Customization',
              link: '/guide/advanced/customization',
            },
            {
              text: 'Markdown',
              link: '/guide/advanced/markdown',
            },
          ],
        },
      ],
    },
  },
});

Type: Object
Default: {}

The footer of the home page.

The footer config is an object of Footer, which has the following types:

export interface Footer {
  message?: string;
}

message is a string that can contain HTML content. This string will be inserted into the footer using dangerouslySetInnerHTML, allowing you to pass in HTML template tags to design your footer.

For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    footer: {
      message:
        '<p>This is a footer with a <a href="https://example.com">link</a> and <strong>bold text</strong></p>',
    },
  },
});

lastUpdated

Type: boolean | { author?: boolean | ((info: { name: string; email: string; filePath: string }) => string) }
Default: false

Whether to display the last updated time of each document page. Rspress reads this value from the file's latest Git commit.

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    lastUpdated: true,
  },
});

When deploying in CI, make sure the Git history is available. For example, use fetch-depth: 0 with actions/checkout on GitHub Actions.

Set author to display the last commit author as well. Pass a function to customize the rendered author text.

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    lastUpdated: {
      author: ({ name, email }) => `${name} <${email}>`,
    },
  },
});

socialLinks

Type: Array
Default: []

You can add related links through the following config, such as github links, x links, etc. Related links support five modes: link text img dom github-stars, for example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: 'github',
        mode: 'link',
        content: 'https://github.com/sanyuan0704/island.js',
      },
      {
        icon: 'wechat',
        mode: 'text',
        content: 'wechat: foo',
      },
      {
        icon: 'qq',
        mode: 'img',
        content: '/qrcode.png',
      },
      {
        icon: 'github',
        mode: 'dom',
        content:
          '<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/rjhwzy/ljhwZthlaukjlkulzlp/rspress/rspress-navbar-logo-0904.png" alt="logo" id="logo" class="mr-4 rspress-logo dark:hidden">',
      },
      {
        icon: 'github',
        mode: 'github-stars',
        content: 'https://github.com/web-infra-dev/rspress',
      },
    ],
  },
});

When in link mode, click the icon to jump to the link.
When in text mode, when the mouse moves over the icon, a pop-up box will be displayed, and the content of the pop-up box is the entered text
When in the img mode, moving the mouse over the icon will display a bullet box, and the content of the bullet box is the specified picture. It should be noted that the picture needs to be placed in the public directory.
When in dom mode, html to render can be passed directly into the content field. Use '' for wrapping
When in github-stars mode, content should be the GitHub repository URL. The repository's star count is fetched from the GitHub REST API and rendered next to the icon. The result is cached in localStorage for one hour to avoid hitting the API rate limit. If the request fails (offline, rate-limited, private repo), the icon falls back to a plain link.

Related links support the following types of images, which can be selected through the icon attribute:

export type SocialLinkIcon =
  | 'lark'
  | 'discord'
  | 'facebook'
  | 'github'
  | 'instagram'
  | 'linkedin'
  | 'slack'
  | 'x'
  | 'youtube'
  | 'wechat'
  | 'qq'
  | 'juejin'
  | 'zhihu'
  | 'bilibili'
  | 'weibo'
  | 'gitlab'
  | 'X'
  | 'bluesky'
  | 'npm'
  | { svg: string };

If you need to customize the icon, you can pass in an object with svg attribute, and the value of svg is the content of the custom icon, for example:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: {
          svg: '<svg>foo</svg>',
        },
        mode: 'link',
        content: 'https://github.com/',
      },
    ],
  },
});

nextPageText

Type: string
Default: Next Page

Text for the next page. for example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    nextPageText: 'Next Page',
  },
});

locales

Type: Array<LocaleConfig>
Default: undefined

I18n config. This config is an array, and every item of it is LocaleConfig, and the types are as follows:

export interface LocaleConfig {
  /**
   * General locale config for site, which will have a higher priority than `locales`
   */
  // language name
  lang?: string;
  // HTML title, takes precedence over `themeConfig.title
  title?: string;
  // HTML description, takes precedence over `themeConfig.description`
  description?: string;
  // Display text for the corresponding language
  label: string;
}

LocaleConfig contains many of the same configuration options as the theme config, but the former will have a higher priority.

darkMode

Type: boolean | 'dark' | 'light' | 'auto' | 'force-light' | 'force-dark' | 'force-auto'
Default: true

When dark mode is active, Rspress adds the dark class to the <html> element. You can use the html.dark selector to customize dark mode styles:

html.dark .custom-content {
  color: white;
}

Configure the Dark/Light mode behavior:

true: same as 'auto'.
false: same as 'force-light'.
'light': show the toggle button and use light mode by default when the user has no saved preference.
'dark': show the toggle button and use dark mode by default when the user has no saved preference.
'auto': show the toggle button and follow the user's system preference by default when the user has no saved preference.
'force-light': always use light mode and hide the toggle button.
'force-dark': always use dark mode and hide the toggle button.
'force-auto': always follow the user's system preference and hide the toggle button.

For example, always use dark mode and hide the toggle button:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    darkMode: 'force-dark',
  },
});

editLink

Type:

interface EditLink {
  /**
   * Custom repository url for edit link.
   */
  docRepoBaseUrl: string;
}

Default: undefined

Display a link to edit the page on Git management services such as GitHub, or GitLab. The link appears in both the doc footer and the right-side outline panel.

For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    editLink: {
      docRepoBaseUrl:
        'https://github.com/web-infra-dev/rspress/tree/main/website/docs',
    },
  },
});

enableContentAnimation

Type: boolean
Default: false

Whether there is animation effect when switching between pages. It is implemented with View Transition API. For example:

The animation is not configurable for now.

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    enableContentAnimation: true,
  },
});

enableAppearanceAnimation

Type: boolean
Default: false

Whether there is animation effect when switching between light and dark theme. It is implemented with View Transition API. For example:

The animation is not configurable for now.

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    enableAppearanceAnimation: true,
  },
});

search

Type: boolean
Default: true

Whether to display the search box. For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    search: false,
  },
});

enableScrollToTop

Type: boolean
Default: true

Enable scroll to top button on documentation. For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    enableScrollToTop: true,
  },
});

localeRedirect

Type: 'auto' | 'never' | 'only-default-lang'
Default: 'auto'

Whether to redirect to the locale closest to window.navigator.language when the user visits the site, the default is auto, which means that the user will be redirected on the first visit. If you set it to never, the user will not be redirected. If you set it to only-default-lang, the user will only be redirected when visiting the default locale. For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    localeRedirect: 'never',
  },
});

fallbackHeadingTitle

Type: boolean
Default: true

Whether to use frontmatter.title as fallback when the document does not have an H1 heading. For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    fallbackHeadingTitle: false,
  },
});

---
title: Document Title
---

## Content

llmsUI

Type:

type LlmsUI =
  | boolean
  | {
      viewOptions?: Array<
        | 'markdownLink'
        | 'chatgpt'
        | 'claude'
        | { title: string; icon?: React.ReactNode; onClick?: () => void }
        | { title: string; href: string; icon?: React.ReactNode }
      >;
      placement?: 'title' | 'outline';
    };

Default: false (automatically set to true when llms: true is configured)

Configuration for LLMS UI components. When enabled, LlmsCopyButton and LlmsViewOptions components will be automatically added below all H1 headers (default), or as rows in the outline panel.

This is useful when using the llms feature to generate llms.txt files, allowing users to easily copy or open the markdown content in AI tools.

Warning

ssg-md only takes effect during the build process, so copying Markdown content in dev mode will not work. Please use rspress build first, then debug with rspress preview. See Differences between dev and build for details.

For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  llms: true, // This will automatically enable llmsUI
  themeConfig: {
    // llmsUI is automatically set to true when llms: true
    // You can also explicitly configure it:
    llmsUI: true,
    // Or with custom options:
    // llmsUI: {
    //   viewOptions: ['markdownLink', 'chatgpt', 'claude'],
    //   placement: 'outline',
    // },
  },
});

viewOptions

Type: Array<'markdownLink' | 'chatgpt' | 'claude' | CustomOption>
Default: ['markdownLink', 'chatgpt', 'claude']

Options for the LlmsViewOptions dropdown menu. Built-in options include:

'markdownLink': Copy markdown file link
'chatgpt': Open in ChatGPT
'claude': Open in Claude

You can also provide custom options with title, href or onClick, and optional icon.

placement

Type: 'title' | 'outline'
Default: 'title'

Controls where the LLMS UI components are displayed.

'title': Show as buttons below the H1 title (default behavior)
'outline': Show as separate rows in the right-side outline panel

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  llms: true,
  themeConfig: {
    llmsUI: {
      placement: 'outline',
    },
  },
});

#Theme config

#nav

#sidebar

#footer

#lastUpdated

#socialLinks

#nextPageText

#locales

#darkMode

#editLink

#enableContentAnimation

#enableAppearanceAnimation

#search

#enableScrollToTop

#localeRedirect

#fallbackHeadingTitle

#llmsUI

#viewOptions

#placement

Theme config

nav

sidebar

footer

lastUpdated

socialLinks

nextPageText

locales

darkMode

editLink

enableContentAnimation

enableAppearanceAnimation

search

enableScrollToTop

localeRedirect

fallbackHeadingTitle

llmsUI

viewOptions

placement