Конфигурация метаданных

На этой странице описывается, как настраивать свойства уровня страницы с помощью метаданных, включая заголовок, описание, тип страницы и видимость навигационной панели.

См. метаданные для получения информации о синтаксисе метаданных и useFrontmatter для получения информации о том, как обращаться к метаданным в коде.

title

Тип: string

Заголовок страницы. По умолчанию Rspress использует H1-заголовок страницы в качестве HTML-заголовка документа. Чтобы задать другой заголовок, укажите его в метаданных:

---
title: Моя главная страница
---

Это **содержимое главной страницы**.

Это то же самое, что и:

# Моя главная страница

Это **содержимое главной страницы**.

description

Тип: string

Пользовательское описание страницы. Rspress использует его для генерации мета-тега <meta name="description" content="..." /> на странице для SEO-оптимизации.

По умолчанию Rspress извлекает первый содержательный абзац под заголовком h1 в качестве описания (см. markdown.extractDescription). Если результат извлечения вас не устраивает, вы можете переопределить его с помощью этого поля. Подробнее см. Настройка тегов head - Как определяется описание.

---
description: Это моя главная страница.
---

pageType

Тип: 'home' | 'doc' | 'doc-wide' | 'custom' | 'blank' | '404'
По умолчанию: 'doc'

Тип страницы. По умолчанию — doc. Чтобы использовать другой тип страницы, задайте поле pageType в метаданных:

---
pageType: home
---

Каждое значение pageType означает следующее:

home: Главная страница, включает верхнюю навигационную панель и контент макета главной страницы.
doc: Страница документации, включает верхнюю навигационную панель, левую боковую панель, основной контент и правое оглавление.
doc-wide: Широкая страница документации, где основной контент может занимать более широкую область при одновременном использовании outline: false и sidebar: false.
custom: Пользовательская страница, включает верхнюю навигационную панель и пользовательский контент.
blank: Также пользовательская страница, но без верхней навигационной панели.
404: Страница «не найдено».

titleSuffix

Тип: string

Устанавливает суффикс заголовка страницы. Если titleSuffix не задан, по умолчанию в качестве суффикса используется title сайта.

---
titleSuffix: 'Генератор статических сайтов на базе Rsbuild'
---

По умолчанию между заголовком и суффиксом используется разделитель -. Также можно использовать |:

---
titleSuffix: '| Генератор статических сайтов на базе Rsbuild'
---

Тип: boolean | 'placeholder'
По умолчанию: true

Управляет отображением левой боковой панели. По умолчанию страницы типа doc отображают левую боковую панель. Чтобы скрыть её, используйте следующие метаданные:

---
sidebar: false
---

Совет

sidebar: false скрывает боковую панель и оставляет заполнитель шириной 12vw слева, чтобы визуально центрировать содержимое на больших экранах. Если вы хотите, чтобы основное содержимое занимало больше места на экране, используйте pageType: doc-wide вместе с sidebar: false:

---
pageType: doc-wide
sidebar: false
---

Основной контент будет расширен и займет пространство, которое обычно используется боковой панелью.

Если вы хотите сохранить пустое пространство для левой боковой панели, используйте sidebar: 'placeholder':

---
sidebar: 'placeholder'
---

outline

Управляет отображением правой панели оглавления. По умолчанию страницы doc отображают правую панель оглавления. Чтобы скрыть её, используйте:

---
outline: false
---

Совет

outline: false только скрывает колонку оглавления, но пространство, ранее занятое колонкой оглавления, остается зарезервированным. Если вы хотите, чтобы основной контент занимал больше места на экране, используйте pageType: doc-wide вместе с outline: false:

---
pageType: doc-wide
outline: false
---

Основной контент будет расширен и займет пространство, которое обычно используется панелью оглавления.

Управляет отображением компонентов в нижней части документации, таких как ссылки на предыдущую и следующую страницы, в нижней части страницы. По умолчанию страницы doc отображают футер. Чтобы скрыть его, используйте:

---
footer: false
---

Управляет отображением верхней навигационной панели. По умолчанию все страницы отображают верхнюю навигационную панель. Чтобы скрыть её, используйте:

---
navbar: false
---

icon

Добавлено в v2.0.19

Тип: string

Задаёт значок, отображаемый перед заголовком страницы в автоматически сгенерированной боковой панели. Для локальных изображений поместите файл в каталог public и укажите его через абсолютный путь:

---
icon: /icon.png
---

Также поддерживаются встроенные строки SVG, эмодзи, внешние URL-адреса и data URL. Если для одного и того же элемента icon задан и во frontmatter, и в _meta.json, приоритет имеет значение из frontmatter.

Дополнительные примеры см. в разделе Значки и метки боковой панели.

context

Тип: string

При настройке Rspress добавляет атрибут data-context с указанным значением к сгенерированному DOM-узлу боковой панели.

foo.mdx

---
context: 'context-foo'
---

bar.mdx

---
context: 'context-bar'
---

DOM-структура окончательно сгенерированной боковой панели сокращена следующим образом:

<div class="rspress-sidebar-group">
  <div className="rspress-sidebar-item" data-context="context-foo"></div>
  <div className="rspress-sidebar-item" data-context="context-bar"></div>
</div>

search

Тип: boolean
По умолчанию: true

Определяет, включать ли текущую страницу во встроенный поисковый индекс. По умолчанию все страницы с pageType: doc индексируются для полнотекстового поиска. Чтобы исключить определённую страницу из результатов поиска, установите search в false:

---
search: false
---

Этот параметр влияет только на встроенный поиск. Страницы с pageType: home всегда исключаются из поискового индекса независимо от значения этого поля.

head

Тип: [string, Record<string, string>][]

Укажите дополнительные теги head, которые будут внедрены для текущей страницы. Они будут добавлены после тегов head, внедренных Rspress глобально.

Например, с их помощью можно задать кастомные мета-теги для Open Graph.

---
head:
  - - meta
    - property: og:url
      content: https://example.com/foo/
  - - meta
    - property: og:image
      content: https://example.com/bar.jpg
# - - [htmlTag]
#   - [attributeName]: [attributeValue]
#     [attributeName]: [attributeValue]
---

Полученные теги head будут следующими:

<head>
  <meta property="og:url" content="https://example.com/foo/" />
  <meta property="og:image" content="https://example.com/bar.jpg" />
</head>

Параметры, связанные с обзорной страницей

Следующие настройки относятся к функции обзорной страницы.

overview

Тип: boolean
По умолчанию: false

Включает функцию обзорной страницы для текущей страницы документации. При значении true текущая страница становится обзорной страницей. Например:

---
overview: true
---

overviewHeaders

Тип: number[]
По умолчанию: [2]

Уровни заголовков, отображаемые на обзорной странице. По умолчанию отображаются заголовки H2. Чтобы показывать другие уровни заголовков, задайте поле overviewHeaders в метаданных:

---
overview: true
overviewHeaders: []
---

---
overviewHeaders: [2, 3]
---

Параметры, связанные с домашней страницей

Следующие настройки относятся к функции домашней страницы.

hero

Тип: Object

Конфигурация hero-блока для страницы home. Имеет следующий тип:

interface Hero {
  name: string;
  text: string;
  tagline: string;
  image?: {
    src: string | { dark: string; light: string };
    alt: string;
    /**
     * `srcset` и `sizes` — это атрибуты тега `<img>`. Подробности использования см. на https://mdn.io/srcset.
     * Если значение задано в виде массива, Rspress объединяет элементы массива через запятую.
     **/
    srcset?: string | string[];
    sizes?: string | string[];
  };
  actions: {
    text: string;
    link: string;
    theme: 'brand' | 'alt';
  }[];
}

Например, используйте следующие метаданные, чтобы задать конфигурацию hero-блока страницы:

---
pageType: home

hero:
  name: Rspress
  text: Решение для документации
  tagline: Современный технологический стек для разработки документации
  actions:
    - theme: brand
      text: Введение
      link: /ru/guide/introduction
    - theme: alt
      text: Быстрый старт
      link: /ru/guide/getting-started
---

При задании hero.text можно использовать символ | в YAML, чтобы вручную управлять переносами строк:

---
pageType: home

hero:
  name: Rspress
  text: |
    Решение для
    документации

Также можно использовать HTML в конфигурации hero-блока страницы:

---
pageType: home

hero:
  name: <span class="hero-name">Rspress</span>
  text: <span class="hero-text">Решение для документации</span>
  tagline: <span class="hero-tagline">Современный технологический стек для разработки документации</span>
  actions:
    - theme: brand
      text: <span class="hero-actions-text">Введение</span>
      link: /guide/introduction
    - theme: alt
      text: <span class="hero-actions-text">Быстрый старт</span>
      link: /guide/getting-started
---

features

Тип: Array
По умолчанию: []

Конфигурация блока features для страницы home. Имеет следующий тип:

interface Feature {
  title: string;
  details: string;
  icon: string;
  // Длина сетки карточек, в настоящее время поддерживаются только [3, 4, 6]
  span?: number;
  // Ссылка карточки, не обязательна.
  link?: string;
}

export type Features = Feature[];

Например, используйте следующие метаданные для указания списка возможностей вашего продукта на странице home:

---
pageType: home

features:
  - title: 'MDX: Пишите контент с гибким синтаксисом'
    details: MDX — это мощный способ написания контента. Вы можете использовать компоненты React в Markdown.
    icon: 📦
  - title: 'Многозначность функций: решение «всё в одном»'
    details: Поддержка полнотекстового поиска, интернационализации и других распространённых функций прямо из коробки.
    icon: 🎨
  - title: 'Высокая расширяемость: несколько путей кастомизации'
    details: Используйте API расширений для настройки UI темы и поведения сборки.
    icon: 🚀
---

#Конфигурация метаданных

#title

#description

#pageType

#titleSuffix

#sidebar

#outline

#footer

#navbar

#icon

#context

#search

#head

#Параметры, связанные с обзорной страницей

#overview

#overviewHeaders

#Параметры, связанные с домашней страницей

#hero

#features