close
Rspress
  • English

      • Customizing head tags

      Adding head tags (such as meta tags) to web pages is crucial for SEO optimization and social media sharing. For example, Open Graph is a web metadata protocol that controls how pages appear when shared on social media platforms.

      Currently, Rspress automatically injects the following head tags:

      TagDescription
      <meta name="generator" content="Rspress v${version}">Identifies the site generator and version
      <meta name="description" content="${description}">Page description, see How description is determined below
      <meta property="og:type" content="website">Open Graph type, fixed as website
      <meta property="og:title" content="${title}">Open Graph title, uses current page title (if available)
      <meta property="og:description" content="${description}">Open Graph description, same as above

      How description is determined

      By default, Rspress extracts the first contentful paragraph below the h1 heading as the page description (see markdown.extractDescription). If the extracted result does not meet your needs, you can specify the description field in frontmatter to override it:

      example.mdx
      ---
description: Custom description for this page.
---

      If you want to add head tags, you can use the following methods:

      Global head configuration

      In rspress.config.ts, you can set HTML metadata (head tags) for all pages. See Basic Config - head for details.

      Frontmatter configuration

      You can modify the title and description fields in frontmatter to change the title and description of individual pages.

      example.mdx
      ---
title: Custom Page Title
description: Custom page description for meta description and Open Graph.
---

      You can also use frontmatter - head to customize page metadata tags for SEO optimization.

      For example, if you want to add <meta property="og:description" content="This is description"> to the <head> tag, you can use frontmatter like this:

      example.mdx
      ---
head:
  - - meta
    - property: og:title
      content: This is title
  - - meta
    - property: og:description
      content: This is description
---

      Head component

      If you need more complex head customization, you can use the Head component provided by Rspress to dynamically set head tags in pages or layout components.

      Rsbuild html.tags configuration

      Through builderConfig.html.tags, you can inject custom content into HTML, such as adding analytics code, scripts, or styles:

      rspress.config.ts
      import { defineConfig } from '@rspress/core';

export default defineConfig({
  builderConfig: {
    html: {
      tags: [
        {
          tag: 'script',
          attrs: {
            src: 'https://cdn.example.com/analytics.js',
          },
        },
      ],
    },
  },
});

      For more configuration details, please refer to the Rsbuild html.tags documentation.

      Difference from Rspress head configuration
      • Rspress head configuration: Can access route-related information, supports dynamically setting head tags based on different pages
      • Rsbuild html.tags: A static build-time configuration, suitable for global uniform tag injection (such as analytics code)

      If you need to dynamically adjust head content based on page routes, use Global head configuration or Head component.