close
Rspress
  • 中文

      • 自定义 Head 标签

      为网页增加 Head 标签（如 meta 标签）对于 SEO 优化和社交媒体分享非常重要。比如 Open Graph 是一种网页元数据协议，用于控制页面在社交媒体平台上分享时的显示效果。

      目前 Rspress 会自动注入以下 Head 标签：

      标签描述
      <meta name="generator" content="Rspress v${version}">标识站点生成器及版本号
      <meta name="description" content="${description}">页面描述，参见下方 description 的获取方式
      <meta property="og:type" content="website">Open Graph 类型，固定为 website
      <meta property="og:title" content="${title}">Open Graph 标题，使用当前页面标题（如果存在）
      <meta property="og:description" content="${description}">Open Graph 描述，同上

      description 的获取方式

      默认情况下，Rspress 会提取 h1 标题下方第一段有内容的段落作为页面描述（参见 markdown.extractDescription）。如果提取结果不满足需求，可以在 frontmatter 中指定 description 字段来覆盖：

      example.mdx
      ---
description: 自定义页面描述。
---
      Tip

      你可以使用 rspress-description-generator agent skill 来自动为所有页面生成 description。详见 Agent Skills。

      如果想增加 Head 标签可以通过以下几种方式：

      全局 Head 配置

      在 rspress.config.ts 中，你可以为所有页面设置 HTML 的 metadata（即 head 标签）。详情请查看 基础配置 - head。

      frontmatter 配置

      你可以调整 frontmatter 中的 title 和 description 字段来修改单个页面的标题和描述。

      example.mdx
      ---
title: 自定义页面标题
description: 自定义页面描述，用于 meta description 和 Open Graph。
---

      也可以使用 frontmatter - head 自定义页面的 metadata 标签以进行 SEO 优化。

      例如，如果你想在 <head> 标签中添加 <meta property="og:description" content="This is description">，你可以这样使用 frontmatter：

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

      Head 组件

      如果你需要更复杂的 Head 定制，可以使用 Rspress 提供的 Head 组件 在页面或布局组件中动态设置 Head 标签。

      useHead hook

      如果你已经在 React 组件内部，并且更偏向使用对象形式声明 head 内容，可以使用 useHead：

      import { useHead } from '@rspress/core/runtime';

export function PageMeta() {
  useHead({
    title: '自定义页面标题',
    meta: [
      {
        name: 'description',
        content: '用于 SEO 和社交分享的自定义页面描述。',
      },
    ],
  });

  return null;
}

      和 Head 组件相比，useHead 在需要依赖 props、状态或复用工具函数来生成最终标签时通常更方便。

      Rsbuild html.tags 配置

      通过 builderConfig.html.tags，你可以向 HTML 中注入自定义内容，比如添加统计代码、脚本或样式：

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

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

      更多配置详情请参考 Rsbuild html.tags 文档。

      与 Rspress head 配置的区别
      • Rspress head 配置：可以获取路由相关信息，支持根据不同页面动态设置 head 标签
      • Rsbuild html.tags：是构建时的静态配置，适用于全局统一的标签注入（如统计代码）

      如果需要根据页面路由动态调整 head 内容，请使用 全局 head 配置、Head 组件 或 useHead hook。