Customizing Page#

Rspress provides several ways for you to customize the content of your pages, including:

• Adding custom global components.
• Adding custom global styles.
• Customizing page layout structure.

Custom Global Components#

In some scenarios, you may need to add some custom global components to the page. The framework provides a config item globalUIComponents to achieve this function.

How to Use#

Add the following config in rspress.config.ts:

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

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

Each item of globalUIComponents can be a string, representing the file path of the component; or it can be an array, the first item is the file path of the component, and the second item is the props object of the component, such as:

import { defineConfig } from 'rspress/config';

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

When you register global components, the framework will automatically render these React components in the theme without manually importing and using them.

Through global components, you can complete many custom functions, such as:

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>;
}

In this way, the content of the component will be rendered in the theme page, such as adding BackToTop button.

In the meanwhile, you can also use the global component to register some side effects, such as:

import { useEffect } from 'react';
import { useLocation } from 'rspress/runtime';

// Need a default export
export default function PluginSideEffect() {
  const { pathname } = useLocation();
  useEffect(() => {
    // Executed when the component renders for the first time
  }, []);

  useEffect(() => {
    // Executed when the route changes
  }, [pathname]);
  return null;
}

This way, side effects of components are executed in the theme page. For example, some of the following scenarios require side effects:

• Redirect for certain page routes.
• Bind click event on the img tag of the page to implement the image zoom function.
• When the route changes, the PV data of different pages are reported.
• ......

Custom Styles#

In some scenarios, you may need to add some global styles on top of the theme UI. The framework provides a configuration item globalStyles to achieve this function.

How to Use#

Add the following configuration in rspress.config.ts:

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

export default defineConfig({
  globalStyles: path.join(__dirname, 'styles/index.css'),
});

Then you can add the following code:

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

In this way, the framework will automatically collect all global styles and merge them into the final style file.

Here are some commonly used global styles:

: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);
}

If you want to know more about the internal global styles, you can check vars.css

Tailwind CSS#

In order to get Tailwind CSS working with Rspress, you can use the following steps:

1. Install Tailwind CSS:

npm install tailwindcss -D

2. Create a postcss.config.js file containing tailwindcss plugin:

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

3. Create a tailwind.config.js file and make sure all the content files are included via content:

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

4. Include the Tailwind directives in your CSS styles file from Custom Styles:

@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

For most up to date configuration, please refer to the official Tailwind CSS documentation.

Custom Layout Structure#

Using pageType#

Rspress provides a pageType configuration for you to customize the layout structure of the page.

Rspress's convention-based routing supports two types of routes, one is document routing, that is, pages written with md(x) files, and the other is component routing, that is, pages written with .jsx/.tsx files.

For the former, you can add the pageType field in the frontmatter to specify the layout structure of the page, such as:

---
pageType: custom
---

For the latter, you can add the following export to specify pageType:

export const frontmatter = {
  // Declare layout type
  pageType: 'custom',
};

pageType can be configured as the following values:

• home: Home page, including the layout content of the top navigation bar and home page.
• doc: Doc page, including top navigation bar, left sidebar, body content, and outline bar on the right.
• custom: Custom page, including top navigation bar and custom content.
• blank: Also belongs to custom page, but does not include Top Navigation Bar.
• 404: Not found page.

Using Fine-grained Switches#

In addition to the pageType page layout level configuration, Rspress also provides more fine-grained switches. You can configure other fields in the frontmatter. These fields and their meanings are as follows:

• navbar: Whether to display the top navigation bar. When you want to hide the top navigation bar, you can set it to false.
• sidebar: Whether to display the sidebar. When you want to hide the sidebar, you can set it to false.
• outline: Whether to display the outline column. When you want to hide the outline column, you can set it to false.
• footer: Whether to display the footer. When you want to hide the footer, you can set it to false.

Example:

---
navbar: false
sidebar: false
outline: false
footer: false
globalUIComponents: false
---

Using URL Parameters as Switches#

In addition, you can use URL parameters to control the layout structure of the page at runtime, such as:

# Hide the navigation bar and outline in the right column
http://YOUR_DOMAIN/foo?navbar=0&outline=0

With URL parameters, you can quickly adjust the layout structure of the page without modifying the source code. These parameters specifically include:

• navbar: Whether to display the navigation bar. When you want to hide the top navigation bar, you can set it to 0.
• sidebar: Whether to display the sidebar. When you want to hide the sidebar, you can set it to 0.
• outline: Whether to display the outline column. When you want to hide the outline column, you can set it to 0.
• footer: Whether to display the footer. When you want to hide the footer, you can set it to 0.
• globalUIComponents: Whether to display the global components. When you want to hide the global components, you can set it to 0.

Custom tags#

Customizing head tag#

In rspress.config.ts, you can custom HTML's metadata (aka head tag) for all pages. We explain it with more details in basic config - head within the api section.

Generate metadata tags#

Within frontmatter, you can also customize your page's metadata tag for SEO optimization.

For example, if you want to add <meta name="description" content="This is description"> in your <head> tag, you can use frontmatter like so:

---
title: This is title
description: This is description
---

Read more details on how to customize open graph images (og:image) and open graph title (og:title) can be seen here in frontmatter config.