Rspress

https://rspress.rs/guide/
Admin
Rspress is a high-performance static site generator built on Rsbuild and React, offering a default...
Tokens:16,984
Snippets:139
Trust Score:6.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Complete Rspress sidebar configuration example

Source: https://rspress.rs/guide/basic/auto-nav-sidebar

An example demonstrating a complete Rspress sidebar configuration, combining file, directory, and custom link definitions. This showcases how different object types can be used together to structure navigation.

```json
[
  "install",
  {
    "type": "file",
    "name": "introduction",
    "label": "Introduction"
  },
  {
    "type": "dir",
    "name": "advanced",
    "label": "Advanced",
    "collapsible": true,
    "collapsed": false
  },
  {
    "type": "custom-link",
    "link": "/my-link",
    "label": "My Link"
  }
]
```

--------------------------------

### Configure `_meta.json` for Nested Directory

Source: https://rspress.rs/guide/default-theme/overview-page

This example shows a simple `_meta.json` configuration for a nested directory, listing the files within that directory that should appear in the overview.

```json
["component", "utils"]

```

--------------------------------

### Example of Rspress sidebar with section headers and dividers

Source: https://rspress.rs/guide/basic/auto-nav-sidebar

Illustrates how to use section headers and dividers to organize Rspress sidebar navigation. This example groups different sections with clear visual separators.

```json
[
  {
    "type": "section-header";
    "label": "Section 1"
  },
  "introduction",
  {
    "type": "divider"
  },
  {
    "type": "section-header";
    "label": "Section 2"
  },
  "advanced"
]
```

--------------------------------

### Preview Rspress build output

Source: https://rspress.rs/guide/basic/ssg

This command allows you to preview the static site generated by Rspress after a production build. It starts a local development server, enabling you to view the output in your browser before deploying it to a hosting service.

```bash
> rspress preview

Preview server running at http://localhost:4173/
```

--------------------------------

### Sidebar Level Configuration Example (String File)

Source: https://rspress.rs/guide/basic/auto-nav-sidebar

Demonstrates how to specify a file in the sidebar configuration using a simple string. The string represents the file name, and Rspress will automatically append the correct extension (e.g., `.mdx`).

```json
[
  "introduction"
]
```

--------------------------------

### Create Component Previews with Rspress

Source: https://rspress.rs/guide/start/introduction

Demonstrates how to use Rspress's preview plugin to automatically generate component previews within MDX files. It shows a React example using Arco Design components to display a list of colored tags.

```jsx
import React from 'react';
import { Tag, Space } from '@arco-design/web-react';
import '@arco-design/web-react/dist/css/arco.css';
const COLORS = [
  'red',
  'orangered',
  'orange',
  'gold',
  'lime',
  'green',
  'cyan',
  'blue',
  'arcoblue',
  'purple',
  'pinkpurple',
  'magenta',
  'gray',
];

export default () => {
  return (
    <Space>
      {COLORS.map((color, i) => (
        <Tag key={i} color={color}>
          {color}
        </Tag>
      ))}
    </Space>
  );
};
```

--------------------------------

### Install Tailwind CSS with npm

Source: https://rspress.rs/guide/basic/custom-page

Installs Tailwind CSS as a development dependency using npm. This is the first step to enable Tailwind CSS support in Rspress.

```bash
npm install tailwindcss -D
```

--------------------------------

### Rspress Markdown Configuration for Code Blocks

Source: https://rspress.rs/guide/basic/use-mdx

Provides examples of configuring Rspress to enable line numbers and set default code wrapping behavior for all code blocks via the `rspress.config.ts` file.

```typescript
export default {
  // ...
  markdown: {
    showLineNumbers: true,
  },
};
```

```typescript
export default {
  // ...
  markdown: {
    defaultWrapCode: true,
  },
};
```

--------------------------------

### Initialize Rspress Configuration

Source: https://rspress.rs/guide/default-theme/navbar

Provides the basic structure for initializing Rspress configuration using `defineConfig`. This snippet includes an empty `nav` array within `themeConfig`, serving as a starting point for custom navigation setup.

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  themeConfig: {
    nav: [],
  },
});
```

--------------------------------

### GitHub Actions Workflow for Rspress Deployment

Source: https://rspress.rs/guide/basic/deploy

This YAML file configures a GitHub Actions workflow to build and deploy an Rspress site to GitHub Pages. It includes steps for checking out the code, setting up Node.js and pnpm, installing dependencies, building the Rspress project, and uploading the artifacts for deployment.

```yaml
name: Deploy Rspress site to Pages

on:
  push:
    branches: [main]

  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Not needed if lastUpdated is not enabled
      - uses: pnpm/action-setup@v3 # pnpm is optional but recommended, you can also use npm / yarn
        with:
          version: 8
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Install dependencies
        run: pnpm install
      - name: Build with Rspress
        run: |
          pnpm run build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: doc_build

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

```

--------------------------------

### Custom Layout with Navbar (React)

Source: https://rspress.rs/guide/advanced/custom-theme

Demonstrates how to build a custom `Layout` component in React for your Rspress theme. This example includes a custom `Navbar` component and exports both `Layout` and `setup` functions.

```tsx
// theme/index.tsx
import { Navbar } from './Navbar';

function Layout() {
  return (
    <div>
      <Navbar />
      <div>Custom Theme Layout</div>
    </div>
  );
}

const setup = () => {};

export * from 'rspress/theme';

export { Layout, setup };

// theme/Navbar.tsx
export function Navbar() {
  return <div>Custom Navbar</div>;
}
```

--------------------------------

### Custom Global Styles Example

Source: https://rspress.rs/guide/basic/custom-page

Example of CSS used with Rspress's `globalStyles` configuration to modify theme variables, such as brand colors and layout widths.

```css
:root {
  --rp-c-brand: #f00;
}
```

```css
:root {
  /* Modify theme color */
  --rp-c-brand: #f00;
  --rp-c-brand-dark: #ffa500;
  --rp-c-brand-darker: #c26c1d;
  --rp-c-brand-light: #f2a65a;
  --rp-c-brand-lighter: #f2a65a;
  /* Modify the width of the left sidebar */
  --rp-sidebar-width: 280px;
  /* Modify the width of the right outline column */
  --rp-aside-width: 256px;
  /* Modify the background of the code block title */
  --rp-code-title-bg: rgba(250, 192, 61, 0.15);
  /* Modify the background of the code block content */
  --rp-code-block-bg: rgba(214, 188, 70, 0.05);
}
```

--------------------------------

### Navbar Level Configuration Example (JSON)

Source: https://rspress.rs/guide/basic/auto-nav-sidebar

Defines the structure for navbar items, including text, link, and active match patterns. This configuration is used when `_meta.json` is placed at the navigation bar level.

```json
[
  {
    "text": "Guide",
    "link": "/guides/introduction",
    "activeMatch": "^/guides/"
  }
]
```

--------------------------------

### Using useI18n with Type Hinting

Source: https://rspress.rs/guide/default-theme/i18n

This example illustrates how to use the `useI18n` hook with generic type arguments to leverage the type definitions from an 'i18n.json' file. This provides autocompletion and type safety for translation keys.

```jsx
import { useI18n } from 'rspress/runtime';

const MyComponent = () => {
  const t = useI18n<typeof import('i18n')>();

  return <div>{t('gettingStarted')}</div>;
};
```

--------------------------------

### Add Rsbuild Plugin for Google Analytics

Source: https://rspress.rs/guide/advanced/extend-build

Integrates Google Analytics into an Rspress project using Rsbuild plugins. This example adds `rsbuild-plugin-google-analytics` to the build process. Ensure `rsbuild-plugin-google-analytics` is installed.

```typescript
import { defineConfig } from 'rspress/config';
import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';

export default defineConfig({
  builderPlugins: [
    pluginGoogleAnalytics({
      // replace this with your Google tag ID
      id: 'G-xxxxxxxxxx',
    }),
  ],
});
```

--------------------------------

### Basic Custom Theme Structure (React)

Source: https://rspress.rs/guide/advanced/custom-theme

When creating a custom theme from scratch, you must define a `theme` directory at the project root. Inside this directory, create an `index.ts` or `index.tsx` file to export your theme's main components, including a `Layout` component and an optional `setup` function.

```tsx
// theme/index.tsx
function Layout() {
  return <div>Custom Theme Layout</div>;
}

// The setup function will be called when the page is initialized. It is generally used to monitor global events, and it can be an empty function
const setup = () => {};

// Export all content of the default theme to ensure that your theme configuration can work properly
export * from 'rspress/theme';

// Export Layout component and setup function
// Note: both must export
export default { Layout, setup };
```

--------------------------------

### Configure Rsbuild Output Directory

Source: https://rspress.rs/guide/advanced/extend-build

Customizes the Rsbuild output directory for Rspress projects. This example changes the root output directory to 'doc_dist'. It requires the `rspress` package.

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  builderConfig: {
    output: {
      distPath: {
        root: 'doc_dist',
      },
    },
  },
});
```

--------------------------------

### Configure Multi-Version in Rspress

Source: https://rspress.rs/guide/default-theme/multi-version

Set up the default version and a list of available versions for multi-version document management using the `multiVersion` configuration in `rspress.config.ts`.

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});
```

--------------------------------

### Build and Preview Rspress Project Scripts

Source: https://rspress.rs/guide/basic/deploy

These npm scripts are used to build the Rspress project for production and preview it locally. The build command generates output in the 'doc_build' directory.

```json
{
  "scripts": {
    "build": "rspress build",
    "preview": "rspress preview"
  }
}
```

--------------------------------

### Configure `_meta.json` for Sub-Preview Page

Source: https://rspress.rs/guide/default-theme/overview-page

This demonstrates how to configure `_meta.json` to create a sub-preview page within a directory, typically by defining an 'index' file with an 'Overview' label.

```json
[
  {
    "type": "file",
    "name": "index",
    "label": "Overview"
  }
]
```

--------------------------------

### Fully Reuse Search Component (React)

Source: https://rspress.rs/guide/advanced/custom-theme

Provides an example of how to fully reuse the built-in search functionality of the Rspress default theme by importing and using the `Search` component directly.

```tsx
import { Search } from 'rspress/theme';

function MySearch() {
  return <Search />;
}
```

--------------------------------

### Configure `_meta.json` for Directory Structure

Source: https://rspress.rs/guide/default-theme/overview-page

This configuration for `_meta.json` defines the structure of an overview page for a directory. It specifies entries as files or directories, along with their display labels.

```json
[
  {
    "type": "file",
    "name": "index",
    "label": "API Overview"
  },
  {
    "type": "dir",
    "name": "theme",
    "label": "Theme"
  }
]
```

--------------------------------

### Global UI Component Implementation in Rspress

Source: https://rspress.rs/guide/basic/custom-page

Example of a default-exported React component intended for use as a global UI component in Rspress. It can optionally receive props defined in the configuration.

```typescript
import React from 'react';

// Need a default export
// The props comes from your config
export default function PluginUI(props?: { foo: string }) {
  return <div>This is a global layout component</div>;
}
```

--------------------------------

### Rspress: File Naming for Custom Sidebar Order

Source: https://rspress.rs/guide/basic/auto-nav-sidebar

This example demonstrates how to prefix filenames with numbers in a directory to control the order in which they appear in the automatically generated sidebar. Files are sorted alphabetically by default if no prefix is used.

```plaintext
basic
  ├── 1-introduction.mdx
  ├── 2-install.mdx
  └── 3-plugin-development.md
```

--------------------------------

### Get Current Language with useLang (React)

Source: https://rspress.rs/guide/advanced/custom-theme

Demonstrates how to use the `useLang` hook from `rspress/runtime` to retrieve the current language setting of the site within a React component.

```tsx
import { useLang } from 'rspress/runtime';

function MyComponent() {
  const lang = useLang();
  return <div>{lang}</div>;
}
```

--------------------------------

### Implement beforeSearch Hook

Source: https://rspress.rs/guide/advanced/custom-search

An example implementation of the `beforeSearch` hook. This hook is executed before the search process begins and can be used to modify the search query, such as removing spaces. It supports asynchronous operations.

```typescript
import type { BeforeSearch } from 'rspress/theme';

const beforeSearch: BeforeSearch = (query: string) => {
  // Some operations before search can be done here
  console.log('beforeSearch');
  // Return the processed query
  return query.replace(' ', '');
};

export { beforeSearch };
```

--------------------------------

### MDX with React Components

Source: https://rspress.rs/guide/start/introduction

Demonstrates using Markdown files with embedded React components in Rspress. MDX allows for rich content creation by blending Markdown syntax with JSX.

```markdown
import { Button } from 'react-components';

# My MDX Page

This is some markdown content.

<Button onClick={() => alert('Hello!')}>Click Me</Button>

## Another Section

More content here.
```

--------------------------------

### Configure MDX Compilation Plugins

Source: https://rspress.rs/guide/advanced/extend-build

Customizes MDX compilation in Rspress by adding remark and rehype plugins. This example uses `remark-autolink-headings` and `rehype-slug`, and specifies `mdxRs: false` to use the JS compiler. Requires `unified`, `remark-autolink-headings`, and `rehype-slug`.

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  markdown: {
    // It's necessary to use JS version compiler
    mdxRs: false,
    remarkPlugins: [
      [
        require('remark-autolink-headings'),
        {
          behavior: 'wrap',
        },
      ],
    ],
    rehypePlugins: [require('rehype-slug')],
  },
});
```

--------------------------------

### Conditionally Use Rust MDX Compiler

Source: https://rspress.rs/guide/basic/use-mdx

This example demonstrates how to conditionally enable the Rust version of the MDX compiler for specific files by providing an `include` function to the `mdxRs` configuration. This allows fine-grained control over which files utilize the faster Rust compiler.

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  markdown: {
    mdxRs: {
      include: (filepath: string) => filepath.includes('foo.mdx'),
    },
  },
});
```

--------------------------------

### Rspress Code Block Basic Usage

Source: https://rspress.rs/guide/basic/use-mdx

Shows the basic syntax for creating code blocks using triple backticks ``` and how to specify the language for syntax highlighting. It also demonstrates adding a title to the code block.

```markdown
```js
console.log('Hello World');
```

```js title="hello.js"
console.log('Hello World');
```
```

--------------------------------

### Programmatic Nav/Sidebar Config (rspress.config.ts)

Source: https://rspress.rs/guide/start/introduction

Illustrates programmatic configuration for Rspress navigation and sidebar by specifying `nav` and `sidebar` in the Rspress config file. This is useful for dynamic configuration scenarios, such as converting TypeDoc data.

```typescript
import type { Config } from '@rspress/core'

const config: Config = {
  // ... other configurations
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Docs', link: '/docs/' },
    ],
    sidebar: {
      '/docs/': [
        { text: 'Introduction', link: '/docs/introduction' },
        { text: 'Installation', link: '/docs/install' },
      ],
    },
  },
}
```

--------------------------------

### MDX Component Usage in Rspress

Source: https://rspress.rs/guide/basic/use-mdx

Demonstrates how to use React components within Markdown files by naming them with the `.mdx` extension and importing them. It also shows how to import other MDX files as components.

```mdx
import { CustomComponent } from './custom';

# Hello world

<CustomComponent />
```

```mdx
import Foo from './shared/foo.mdx';

# Hello world

<Foo />
```

```mdx
// <cwd>/docs/index.mdx
import { Button } from '../components/button';

# Button

<Button />

// <cwd>/components/button.mdx
export Button = () => <button />;
```

--------------------------------

### Declarative Nav/Sidebar Config (_meta.json)

Source: https://rspress.rs/guide/start/introduction

Configuration for Rspress navigation bar and sidebar using a declarative approach with a _meta.json file. This method is recommended for its conciseness and intuitive mapping to the file directory structure.

```json
["introduction", "install", "start"]
```

--------------------------------

### Configure Rspress Home Page with Frontmatter

Source: https://rspress.rs/guide/default-theme/home-page

Defines the content of the Rspress home page using frontmatter. This includes hero section with name, text, tagline, and actions, as well as features with titles, details, and icons. No external dependencies are required for this configuration.

```markdown
---
pageType: home

hero:
  name: Rspress
  text: A documentation solution
  tagline: A modern documentation development technology stack
  actions:
    - theme: brand
      text: Introduction
      link: /en/guide/introduction
    - theme: alt
      text: Quick Start
      link: /en/guide/getting-started

features:
  - title: 'MDX Support'
    details: MDX is a powerful way to write content. You can use React components in Markdown.
    icon: 📦
  - title: 'Feature Rich'
    details: Out of box support for i18n, full-text search etc.
    icon: 🎨
  - title: 'Customizable'
    details: You can customize the theme ui and the build process.
    icon: 🚀
---

```

--------------------------------

### GitHub Markdown Alerts Syntax in Rspress

Source: https://rspress.rs/guide/basic/use-mdx

Demonstrates the use of GitHub Flavored Markdown (GFM) alert syntax (e.g., `> [!NOTE]`) for creating custom content blocks with predefined types.

```markdown
> [!NOTE]
> This is a `block` of type `note`

> [!TIP]
> This is a `block` of type `tip`

> [!INFO]
> This is a `block` of type `info`

> [!WARNING]
> This is a `block` of type `warning`

> [!DANGER]
> This is a `block` of type `danger`

> [!DETAILS]
> This is a `block` of type `details`
```

--------------------------------

### Implement afterSearch Hook

Source: https://rspress.rs/guide/advanced/custom-search

An example of the `afterSearch` hook, executed after search results are rendered. This hook provides access to the final search query and the complete search results, supporting asynchronous operations.

```typescript
import type { AfterSearch } from 'rspress/theme';

const afterSearch: AfterSearch = async (query, searchResult) => {
  // Search keyword
  console.log(query);
  // Search result
  console.log(searchResult);
};

export { afterSearch };
```

--------------------------------

### Configure Navigation Bar with i18n Key

Source: https://rspress.rs/guide/default-theme/i18n

Demonstrates how to use an i18n key (e.g., 'guide') for the 'text' field in `_meta.json` to enable automatic translation of navigation bar items.

```json
[
  {
    "text": "guide",
    "link": "/guide/start/getting-started",
    "activeMatch": "/guide/"
  }
]
```

--------------------------------

### Configure Sidebar with i18n Key

Source: https://rspress.rs/guide/default-theme/i18n

Shows how to use an i18n key (e.g., 'gettingStarted') for the 'label' field in `_meta.json` to ensure sidebar directory or item names are automatically translated.

```json
[
  {
    "type": "dir",
    "name": "start",
    "label": "gettingStarted"
  }
]
```

--------------------------------

### Enable Content and Appearance Animations in Rspress

Source: https://rspress.rs/guide/start/introduction

Configures Rspress to use the View Transition API for smooth page transition animations. It enables both content and appearance animations via theme configuration for an enhanced user experience.

```javascript
export default defineConfig({
  themeConfig: {
    // Enable View Transition transition
    enableContentAnimation: true,
    enableAppearanceAnimation: true,
  },
});
```

--------------------------------

### Configure Rspress Navigation Menu with Links and Groups

Source: https://rspress.rs/guide/default-theme/navbar

Demonstrates how to define the navigation bar structure in Rspress using `themeConfig.nav`. It shows how to add single links with text and URLs, and how to create dropdown menus (`NavItemWithChildren`) with multiple nested links. The example also illustrates positioning items to the 'left' of the navbar.

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Home',
        link: '/',
        position: 'left',
      },
      {
        text: 'Links',
        items: [
          {
            text: 'GitHub',
            link: 'http://github.com/',
          },
          {
            text: 'X',
            link: 'http://x.com/',
          },
        ],
        position: 'left',
      },
    ],
  },
});
```

--------------------------------

### Front Matter in Rspress MDX

Source: https://rspress.rs/guide/basic/use-mdx

Illustrates how to define metadata using YAML front matter at the beginning of MDX files and how to access these properties within the content.

```mdx
---
title: Hello world
---

# {frontmatter.title}
```

--------------------------------

### Get Current Version in Rspress Components

Source: https://rspress.rs/guide/default-theme/multi-version

Access the currently active version within Rspress components using the `useVersion` hook from the `rspress/runtime` library. This allows dynamic display or logic based on the version.

```typescript
import { useVersion } from 'rspress/runtime';

export default () => {
  const version = useVersion();
  return <div>Current version: {version}</div>;
};
```

--------------------------------

### Configure Rspress Root Directory

Source: https://rspress.rs/guide/basic/static-assets

Sets the root directory for Rspress documentation files. This directory contains the main content and assets for your site.

```typescript
import { defineConfig } from 'rspress/config';

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

--------------------------------

### Configure Frontmatter for Overview Page

Source: https://rspress.rs/guide/default-theme/overview-page

This snippet demonstrates how to set the 'overview' frontmatter property to 'true' in a Markdown file to designate it as an overview page. It also shows how to optionally set a 'title' for the overview page.

```markdown
---
overview: true
---

```

```markdown
---
overview: true
title: Overview
---

This is an Overview page of our website.

```

--------------------------------

### Comprehensive Rspress Theme Slot Customization

Source: https://rspress.rs/guide/advanced/custom-theme

Illustrates the extensive customization options available through Rspress theme slots. This example shows how to inject custom JSX content into various layout positions, including before/after heroes, features, footers, docs, and navigation elements, as well as custom MDX components.

```tsx
import Theme from 'rspress/theme';

const Layout = () => (
  <Theme.Layout
    /* Before home hero */
    beforeHero={<div>beforeHero</div>}
    /* After home hero */
    afterHero={<div>afterHero</div>}
    /* Before home features */
    beforeFeatures={<div>beforeFeatures</div>}
    /* After home features */
    afterFeatures={<div>afterFeatures</div>}
    /* Before doc footer */
    beforeDocFooter={<div>beforeDocFooter</div>}
    /* After doc footer */
    afterDocFooter={<div>afterDocFooter</div>}
    /* Doc page front */
    beforeDoc={<div>beforeDoc</div>}
    /* Doc page end */
    afterDoc={<div>afterDoc</div>}
    /* Doc content front */
    beforeDocContent={<div>beforeDocContent</div>}
    /* Doc content end */
    afterDocContent={<div>afterDocContent</div>}
    /* Before the nav bar */
    beforeNav={<div>beforeNav</div>}
    /* Before the title of the nav bar in the upper left corner */
    beforeNavTitle={<span>😄</span>}
    /* Nav bar title */
    navTitle={<div>Custom Nav Title</div>}
    /* After the title of the nav bar in the upper left corner */
    afterNavTitle={<div>afterNavTitle</div>}
    /* The right corner of the nav menu */
    afterNavMenu={<div>afterNavMenu</div>}
    /* Above the left sidebar */
    beforeSidebar={<div>beforeSidebar</div>}
    /* Below the left sidebar */
    afterSidebar={<div>afterSidebar</div>}
    /* Above the right outline column */
    beforeOutline={<div>beforeOutline</div>}
    /* Below the outline column on the right */
    afterOutline={<div>afterOutline</div>}
    /* Top of the entire page */
    top={<div>top</div>}
    /* Bottom of the entire page */
    bottom={<div>bottom</div>}
    /* Custom MDX components */
    components={{ p: (props) => <p {...props} className="my-4 leading-7" /> }}
  />
);

export default {
  ...Theme,
  Layout,
};

export * from 'rspress/theme';
```

--------------------------------

### Implement onSearch Hook with Custom Results

Source: https://rspress.rs/guide/advanced/custom-search

This example demonstrates the `onSearch` hook, which runs after the default search logic. It allows filtering default results, adding custom data sources, and logging search queries and results. The hook supports asynchronous operations and returns custom search results.

```typescript
import type { OnSearch } from 'rspress/theme';
import { RenderType } from 'rspress/theme';

const onSearch: OnSearch = async (query, defaultSearchResult) => {
  // Can request data based on query
  console.log(query);
  // The results of the default search source, which is an array
  console.log(defaultSearchResult);
  // const customResult = await searchQuery(query);

  // Can directly operate the default search results.
  defaultSearchResult.pop();

  // The return value is an array, each item in the array is a search source result, and they will be added to the search result
  return [
    {
      group: 'Custom',
      result: {
        list: [
          {
            title: 'Search Result 1',
            path: '/search1',
          },
          {
            title: 'Search Result 2',
            path: '/search2',
          },
        ],
      },
      renderType: RenderType.Custom,
    },
  ];
};

export { onSearch };
```

--------------------------------

### Configure Tailwind CSS

Source: https://rspress.rs/guide/basic/custom-page

Creates the Tailwind CSS configuration file, specifying content files to scan for classes and allowing for theme extensions and custom plugins.

```javascript
module.exports = {
  content: ['./src/**/*.tsx', './docs/**/*.mdx'],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

--------------------------------

### Custom Container Syntax in Rspress

Source: https://rspress.rs/guide/basic/use-mdx

Shows the `:::` syntax for creating custom content blocks with titles, including default types like 'note', 'tip', 'info', 'warning', 'danger', and 'details', as well as custom titles.

```markdown
:::note
This is a `block` of type `note`
:::

:::tip
This is a `block` of type `tip`
:::

:::info
This is a `block` of type `info`
:::

:::warning
This is a `block` of type `warning`
:::

:::danger
This is a `block` of type `danger`
:::

:::details
This is a `block` of type `details`
:::

:::tip Custom Title
This is a `block` of `Custom Title`
:::

:::tip{title="Custom Title"}
This is a `block` of `Custom Title`
:::
```

--------------------------------

### Get Page Data with usePageData (React)

Source: https://rspress.rs/guide/advanced/custom-theme

Utilizes the `usePageData` hook from `rspress/runtime` to access all site-related data within a React component. This hook returns an object containing information such as the page title.

```tsx
import { usePageData } from 'rspress/runtime';

function MyComponent() {
  const pageData = usePageData();
  return <div>{pageData.title}</div>;
}
```

--------------------------------

### Configure Static Resource Prefix in Rspress

Source: https://rspress.rs/guide/basic/deploy

Configure the base URL for static resources (like JS, CSS, images) to be served from a CDN. This involves setting the `assetPrefix` option within `builderConfig.output`.

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  builderConfig: {
    output: {
      assetPrefix: 'https://cdn.com/',
    },
  },
});
```

--------------------------------

### Configure Homepage Hero Image in Rspress

Source: https://rspress.rs/guide/basic/static-assets

Sets the hero image for the Rspress homepage using frontmatter. Supports external links and absolute paths.

```markdown
---
pageType: home

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

```

```markdown
---
pageType: home

hero:
  image:
    src: '/rspress-logo.png'
    alt: Rspress
---

```

--------------------------------

### Configure Project Base Path in Rspress

Source: https://rspress.rs/guide/basic/deploy

Set the base path for your Rspress project when deploying to a sub-directory of a domain (e.g., `https://foo.github.io/bar/`). This is done by configuring the `base` parameter.

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  base: '/bar/',
});
```

--------------------------------

### Describe a file in Rspress sidebar

Source: https://rspress.rs/guide/basic/auto-nav-sidebar

Defines a file entry for the Rspress sidebar. Includes properties like 'name', 'label', 'overviewHeaders', and 'context'. The 'name' can include or omit the file suffix. 'label' defaults to the document's H1 title if not provided. 'overviewHeaders' specifies headers for the overview page (defaults to [2]). 'context' adds a 'data-context' attribute to the DOM node.

```json
{
  "type": "file";
  "name": "introduction",
  "label": "Introduction"
}
```

--------------------------------

### Configure Rspress Site and Theme Locales

Source: https://rspress.rs/guide/default-theme/i18n

Configures site-wide information (like title and description) and theme-specific settings (like outline titles) for different languages in `rspress.config.ts`.

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  locales: [
    {
      lang: 'en',
      // The label in nav bar to switch language
      label: 'English',
      title: 'Rspress',
      description: 'Static Site Generator',
    },
    {
      lang: 'zh',
      label: '简体中文',
      title: 'Rspress',
      description: '静态网站生成器',
    },
  ],
  themeConfig: {
    locales: [
      {
        lang: 'en',
        outlineTitle: 'ON THIS Page',
      },
      {
        lang: 'zh',
        outlineTitle: '大纲',
      },
    ],
  },
});
```

--------------------------------

### Customizing Anchor IDs in Rspress

Source: https://rspress.rs/guide/basic/use-mdx

Demonstrates how to manually specify an ID for headers in Markdown files, allowing for custom anchor links, by appending `{#custom-id}` to the header text.

```markdown
## Hello world {#custom-id}
```

--------------------------------

### Render MDX Content with Content (React)

Source: https://rspress.rs/guide/advanced/custom-theme

Shows how to use the `Content` component from `rspress/runtime` within a React `Layout` component to render the main content of an MDX page.

```tsx
import { Content } from 'rspress/runtime';

function Layout() {
  return (
    <div>
      <Content />
    </div>
  );
}
```

--------------------------------

### Rspress Code Block Line Highlighting

Source: https://rspress.rs/guide/basic/use-mdx

Explains how to highlight specific lines within a code block and simultaneously add a title to the code block using a combination of `{}` for line numbers and `title=""`.

```markdown
```js title="hello.js" {1,3-5}
console.log('Hello World');

const a = 1;

console.log(a);

const b = 2;

console.log(b);
```
```

--------------------------------

### Customizing Rspress Home and 404 Pages

Source: https://rspress.rs/guide/advanced/custom-theme

Shows how to customize specific Rspress page components, such as the Home page (`HomeLayout`) and the 404 Not Found page (`NotFoundLayout`), in addition to extending the main layout. It also demonstrates how to create a custom Search component.

```tsx
import Theme, { Search } from 'rspress/theme';

// Use slot
const Layout = () => <Theme.Layout beforeNavTitle={<div>some content</div>} />;
// Custom Home Page
const HomeLayout = () => <div>Home</div>;
// Custom 404 page
const NotFoundLayout = () => <div>404</div>;

export default {
  ...Theme,
  Layout,
  HomeLayout,
  NotFoundLayout,
};

// Custom Search Component
const MySearch = () => (
  <div className="my-search">
    <Search />
  </div>
);
export { MySearch as Search };
// re-export
export * from 'rspress/theme';
```

--------------------------------

### Reference Image with Absolute Path from Public Directory

Source: https://rspress.rs/guide/basic/static-assets

Illustrates referencing an image located in the `public` directory using an absolute path. Rspress automatically maps these paths to the build output.

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

--------------------------------

### Basic Theme Structure in Rspress

Source: https://rspress.rs/guide/advanced/custom-theme

Defines the fundamental directory structure and the entry point for a custom Rspress theme. It shows how to create a theme directory and an index.tsx file to export theme content.

```plaintext
└── theme
    └── index.tsx
```

--------------------------------

### Configure PostCSS for Tailwind CSS

Source: https://rspress.rs/guide/basic/custom-page

Sets up the PostCSS configuration file to include the Tailwind CSS plugin. This file is essential for PostCSS to process Tailwind directives.

```javascript
module.exports = {
  plugins: {
    tailwindcss: {},
  },
};
```

--------------------------------

### Configure Rspress Outline Title

Source: https://rspress.rs/guide/default-theme/doc-page

This Rspress configuration snippet shows how to set the title for the outline bar using the `outlineTitle` option within the `themeConfig`.

```typescript
import {
  defineConfig
} from 'rspress/config';
import path from 'path';

export default defineConfig({
  themeConfig: {
    outlineTitle: 'ON THIS PAGE',
  },
});
```

--------------------------------

### Handle Base Path for Absolute Image Paths in MDX

Source: https://rspress.rs/guide/basic/static-assets

Explains how to use `normalizeImagePath` from `rspress/runtime` to correctly reference absolute paths when a `base` path is configured for the site. This ensures images are loaded correctly regardless of the deployment structure.

```javascript
import { normalizeImagePath } from 'rspress/runtime';

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

--------------------------------

### Reference Image with Relative Path in MDX

Source: https://rspress.rs/guide/basic/static-assets

Shows how to use an `<img>` tag with a relative path to an image within an MDX file. This allows for more HTML-like integration of images.

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

--------------------------------

### Use Rspress Full Text Search Hook

Source: https://rspress.rs/guide/advanced/custom-theme

Demonstrates how to use the `useFullTextSearch` hook from `rspress/theme` to perform full-text searches. It includes checking the initialization status and calling the search function with keywords.

```typescript
import { useFullTextSearch } from 'rspress/theme';
import { useEffect } from 'react';

function MySearch() {
  const { initialized, search } = useFullTextSearch();

  useEffect(() => {
    async function searchSomeKeywords(keywords: string) {
      if (initialized) {
        // Search for keywords
        const results = await search(keywords);
        console.log(results);
      }
    }
    searchSomeKeywords('keyword');
  }, [initialized]);

  return <div>Search</div>;
}
```

--------------------------------

### Describe a directory in Rspress sidebar

Source: https://rspress.rs/guide/basic/auto-nav-sidebar

Defines a directory entry for the Rspress sidebar. Properties include 'name', 'label', 'collapsible', 'collapsed', 'overviewHeaders', and 'context'. 'name' is the directory name, and 'label' is its display name. 'collapsible' and 'collapsed' control directory behavior. 'overviewHeaders' sets headers for overview pages (defaults to [2]). 'context' adds a 'data-context' attribute.

```json
{
  "type": "dir";
  "name": "advanced",
  "label": "Advanced",
  "collapsible": true,
  "collapsed": false
}
```

--------------------------------

### Sidebar Level Configuration Item Types (TypeScript)

Source: https://rspress.rs/guide/basic/auto-nav-sidebar

Defines the various types of items that can be used in sidebar level `_meta.json` configurations. This includes files, directories, dividers, section headers, and custom links, each with specific properties.

```typescript
export type SideMetaItem =
  | string
  | {
      type: 'file';
      name: string;
      label?: string;
      tag?: string;
      overviewHeaders?: number[];
      context?: string;
    }
  | {
      type: 'dir';
      name: string;
      label?: string;
      collapsible?: boolean;
      collapsed?: boolean;
      tag?: string;
      overviewHeaders?: number[];
      context?: string;
    }
  | {
      type: 'divider';
      dashed?: boolean;
    }
  | {
      type: 'section-header';
      label: string;
      tag?: string;
    }
  | {
      type: 'custom-link';
      label: string;
      link: string;
      context?: string;
    };
```

--------------------------------

### Configure Favicon Icon in Rspress

Source: https://rspress.rs/guide/basic/static-assets

Sets the favicon for the Rspress site. Supports external links, absolute paths, relative paths, and file protocol URLs.

```typescript
import { defineConfig } from 'rspress/config';

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

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  icon: '/favicon.ico',
});
```

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  icon: './docs/public/favicon.ico',
});
```

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  icon: 'file:///local_path/favicon.ico',
});
```

--------------------------------

### Configure Rspress Previous/Next Page Text

Source: https://rspress.rs/guide/default-theme/doc-page

This Rspress configuration snippet demonstrates how to customize the text displayed for the previous and next page links using `prevPageText` and `nextPageText` within `themeConfig`.

```typescript
import {
  defineConfig
} from 'rspress/config';

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

--------------------------------

### Define Rspress i18n Text Data

Source: https://rspress.rs/guide/default-theme/i18n

Defines the structure for internationalization text data in a JSON file. This data can be used in both configuration files and custom components.

```json
{
  "gettingStarted": {
    "en": "Getting Started",
    "zh": "开始"
  },
  "features": {
    "en": "Features",
    "zh": "特性"
  },
  "guide": {
    "en": "Guide",
    "zh": "指南"
  }
}
```

--------------------------------

### Set Default Language in Rspress

Source: https://rspress.rs/guide/default-theme/i18n

Configures the default language for the Rspress site. This is crucial as routes in the default language will have their language prefix removed for cleaner URLs.

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  lang: 'en',
});
```

--------------------------------

### Add Global UI Components in Rspress

Source: https://rspress.rs/guide/basic/custom-page

Configure Rspress to include global UI components. This allows injecting custom React components into the theme. Supports passing props to these components.

```typescript
import { defineConfig } from 'rspress/config';
import path from 'path';

export default defineConfig({
  globalUIComponents: [path.join(__dirname, 'components', 'MyComponent.tsx')],
});
```

```typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  globalUIComponents: [
    [
      path.join(__dirname, 'components', 'MyComponent.tsx'),
      {
        foo: 'bar',
      },
    ],
  ],
});
```

--------------------------------

### Utilize react-router-dom Hooks (React)

Source: https://rspress.rs/guide/advanced/custom-theme

Illustrates how to directly use hooks from `react-router-dom`, such as `useLocation`, within your Rspress theme components, as the framework internally uses this library for routing.

```tsx
import { useLocation } from 'rspress/runtime';

function Layout() {
  const location = useLocation();
  return <div>Current location: {location.pathname}</div>;
}
```

--------------------------------

### Disable Layout Components via Frontmatter

Source: https://rspress.rs/guide/basic/custom-page

Hides specific layout components such as the navigation bar, sidebar, outline, and footer by setting their corresponding keys to 'false' in the frontmatter.

```markdown
---
navbar: false
sidebar: false
outline: false
footer: false
globalUIComponents: false
---
```
Tokens:
Raw