> For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt.
# Customizing head tags / SEO
Adding head tags (such as meta tags) to web pages is crucial for SEO optimization and social media sharing. For example, [Open Graph](https://ogp.me/) is a web metadata protocol that controls how pages appear when shared on social media platforms.
Currently, Rspress automatically injects the following head tags:
| Tag | Description |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `` | Identifies the site generator and version |
| `` | Page description, see [How description is determined](#how-description-is-determined) below |
| `` | Open Graph type, fixed as `website` |
| `` | Open Graph title, uses current page title (if available) |
| `` | Open Graph description, same as above |
| `` | Alternate language versions of the current page on multilingual sites |
| `` | Performance optimization that preloads the current page's async route chunk |
## How description is determined
By default, Rspress extracts the first contentful paragraph below the `h1` heading as the page description (see [`markdown.extractDescription`](https://rspress.rs/api/config/config-build.md#markdownextractdescription)). If the extracted result does not meet your needs, you can specify the `description` field in [frontmatter](https://rspress.rs/api/config/config-frontmatter.md#description) to override it:
```md title="example.mdx"
---
description: Custom description for this page.
---
```
:::tip
You can use the [rspress-description-generator](https://github.com/rstackjs/agent-skills#rspress-description-generator) agent skill to automatically generate descriptions for all pages. See [Agent Skills](https://rspress.rs/guide/start/ai.md#agent-skills) for more details.
:::
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](https://rspress.rs/api/config/config-basic.md#head) for details.
## Frontmatter configuration
You can modify the [title](https://rspress.rs/api/config/config-frontmatter.md#title) and [description](https://rspress.rs/api/config/config-frontmatter.md#description) fields in frontmatter to change the title and description of individual pages.
```md title="example.mdx"
---
title: Custom Page Title
description: Custom page description for meta description and Open Graph.
---
```
You can also use [frontmatter - head](https://rspress.rs/api/config/config-frontmatter.md#head) to customize page metadata tags for SEO optimization.
For example, if you want to add `` to the `` tag, you can use frontmatter like this:
```md title="example.mdx"
---
head:
- - meta
- property: og:title
content: This is title
- - meta
- property: og:description
content: This is description
---
```
You can use the same `head` frontmatter field to add a `` tag:
```md title="example.mdx"
---
head:
- - meta
- name: keywords
content: Rspress, React, static site generator
---
```
## Head component
If you need more complex head customization, you can use the [Head component](https://rspress.rs/ui/runtime-components/head.md) provided by Rspress to dynamically set head tags in pages or layout components.
## useHead hook
If you are already inside a React component and prefer object-based declarations, use [`useHead`](https://rspress.rs/ui/hooks/use-head.md):
```tsx
import { useHead } from '@rspress/core/runtime';
export function PageMeta() {
useHead({
title: 'Custom Page Title',
meta: [
{
name: 'description',
content: 'Custom page description for SEO and social sharing.',
},
],
});
return null;
}
```
Compared with `Head`, `useHead` is usually more convenient when the final tags depend on props, state, or reusable helper functions.
## Rsbuild html.tags configuration
Through `builderConfig.html.tags`, you can inject custom content into HTML, such as adding analytics code, scripts, or styles:
```ts title="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, see the [Rsbuild html.tags documentation](https://rsbuild.rs/config/html/tags).
:::tip Difference from Rspress head configuration
- **Rspress head configuration**: Can access route-related information and dynamically set head tags for different pages.
- **Rsbuild html.tags**: A static build-time configuration suitable for globally injecting the same tags, such as analytics code.
If you need to dynamically adjust head content based on page routes, use [Global head configuration](#global-head-configuration), the [Head component](#head-component), or the [useHead hook](#usehead-hook).
:::