#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.
• ......

#Custom styles

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

#How to use

Add the following configuration in rspress.config.ts:

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

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 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.
• 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.

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:

---
head:
  - - meta
    - name: title
      content: This is title
  - - meta
    - name: description
      content: This is description
---

#Open Graph tags

Open Graph is a web metadata protocol used to control how pages are displayed when shared on social media platforms.

Rspress automatically injects the following Open Graph meta tags for each page:

• og:type: Fixed value of website
• og:title: Automatically uses the current page's title

If you need to customize more Open Graph tags (such as og:image, og:title, etc.), please refer to frontmatter configuration.