#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. Rspress provides a config item globalUIComponents to achieve this function.

#How to use

Add the following config in rspress.config.ts:

import { defineConfig } from '@rspress/core';
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/core';

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

When you register global components, Rspress 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/core/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.
• ......

#Tailwind CSS

To use Tailwind CSS in Rspress, you can follow these steps:

1. Install Tailwind CSS:

npm install tailwindcss -D

yarn add tailwindcss -D

pnpm add tailwindcss -D

bun add tailwindcss -D

deno add npm: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, refer to globalStyles:

@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

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

#Using pageType

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.
• doc-wide: Wide doc page, when using the outline: false and sidebar: false settings together, the main content will automatically occupy a wider screen space.
• 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.
• globalComponents: Whether to display global components. When you want to hide global components, you can set it to false.

Example:

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