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

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

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

#title

• Тип: string

Заголовок страницы. По умолчанию в качестве заголовка HTML-документа используется заголовок первого уровня (H1) страницы. Если нужно задать другой заголовок, можно указать его через метаданные. Например:

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

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

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

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

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

#description

• Тип: string

Пользовательское описание для страницы, которое генерирует мета-тег для оптимизации SEO. Например:

---
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'
---

#sidebar

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

---
sidebar: false
---

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

#outline

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

---
outline: false
---

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

#footer

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

---
footer: false
---

#navbar

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

---
navbar: false
---

#context

• Тип: string

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

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

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

#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: []
---

Or

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

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

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

#hero

• Тип: Object

Конфигурация блока hero (главного баннера) на домашней странице. Имеет следующую структуру:

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: Благодаря механизму расширений вы можете легко настроить UI темы и добавить новые возможности.
    icon: 🚀
---