Перейти к содержимому

Метаданные

Вы можете настроить отдельные страницы Markdown и MDX в Starlight, задав значения в их метаданных. Например, на обычной странице можно задать поля title и description:

src/content/docs/example.md
---
title: Об этом проекте
description: Узнайте больше о проекте, над которым я работаю.
---
Добро пожаловать на страницу «О сайте»!

Поля метаданных

title (обязательно)

тип: string

Вы должны указать заголовок для каждой страницы. Это будет отображаться в верхней части страницы, на вкладках браузера и в метаданных страницы.

description

тип: string

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

slug

type: string

Переопределите slug страницы. Более подробную информацию вы найдете в разделе Определение пользовательских слагов в документации Astro.

editUrl

тип: string | boolean

Переопределяет глобальную конфигурацию editLink. Установите значение false, чтобы отключить ссылку «Редактировать страницу» для конкретной страницы или предоставить альтернативный URL, по которому можно редактировать содержимое этой страницы.

тип: HeadConfig[]

Вы можете добавить дополнительные теги в <head> вашей страницы, используя поле head метаданных. Это означает, что вы можете добавлять пользовательские стили, метаданные и другие теги на одну страницу. Аналогично глобальной опции head.

src/content/docs/example.md
---
title: О нас
head:
# Используем свой тег <title>
- tag: title
content: Пользовательский заголовок
---

tableOfContents

тип: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }

Переопределяет глобальную конфигурацию tableOfContents. Настройте уровни заголовков, которые будут включены, или установите значение false, чтобы скрыть оглавление на этой странице.

src/content/docs/example.md
---
title: Страница, содержащая только H2 в оглавлении
tableOfContents:
minHeadingLevel: 2
maxHeadingLevel: 2
---
src/content/docs/example.md
---
title: Страница без оглавления
tableOfContents: false
---

template

тип: 'doc' | 'splash'
по умолчанию: 'doc'

Установите шаблон макета для этой страницы. Страницы используют макет 'doc' по умолчанию. Установите значение 'splash', чтобы использовать более широкий макет без боковых панелей, предназначенный для целевых страниц.

hero

тип: HeroConfig

Добавьте компонент hero в верхнюю часть этой страницы. Хорошо сочетается с template: splash.

Например, в этом конфиге показаны некоторые общие опции, включая загрузку изображения из вашего репозитория.

src/content/docs/example.md
---
title: Моя домашняя страница
template: splash
hero:
title: 'Мой проект: Быстрая доставка в космосе'
tagline: Доставьте свои вещи на Луну и обратно в мгновение ока.
image:
alt: Сверкающий, ярко раскрашенный логотип
file: ~/assets/logo.png
actions:
- text: Расскажите мне больше
link: /getting-started/
icon: right-arrow
variant: primary
- text: Просмотр на GitHub
link: https://github.com/astronaut/my-project
icon: external
attrs:
rel: me
---

Вы можете отображать разные версии главного изображения в светлом и тёмном режимах.

src/content/docs/example.md
---
hero:
image:
alt: Сверкающий, ярко раскрашенный логотип
dark: ~/assets/logo-dark.png
light: ~/assets/logo-light.png
---

HeroConfig

interface HeroConfig {
title?: string;
tagline?: string;
image?:
| {
// Относительный путь к изображению в вашем репозитории.
file: string;
// Alt-текст, чтобы сделать изображение доступным для вспомогательных технологий
alt?: string;
}
| {
// Относительный путь к изображению в вашем репозитории, которое будет использоваться для тёмного режима.
dark: string;
// Относительный путь к изображению в вашем репозитории, которое будет использоваться для светлого режима.
light: string;
// Alt-текст, чтобы сделать изображение доступным для вспомогательных технологий
alt?: string;
}
| {
// Необработанный HTML для использования в слоте изображения.
// Это может быть пользовательский тег `<img>` или встроенный `<svg>`.
html: string;
};
actions?: Array<{
text: string;
link: string;
variant: 'primary' | 'secondary' | 'minimal';
icon: string;
attrs?: Record<string, string | number | boolean>;
}>;
}

тип: { content: string }

Отображает баннер объявления в верхней части этой страницы.

Значение content может включать HTML для ссылок или другого содержимого. Например, на этой странице отображается баннер со ссылкой на example.com.

src/content/docs/example.md
---
title: Страница с баннером
banner:
content: |
Мы только что запустили нечто крутое!
<a href="https://example.com">Проверьте</a>
---

lastUpdated

тип: Date | boolean

Переопределяет глобальную опцию lastUpdated. Если указана дата, она должна быть действительной временной меткой YAML и будет переопределять дату, хранящуюся в истории Git для этой страницы.

src/content/docs/example.md
---
title: Страница с пользовательской датой последнего обновления
lastUpdated: 2022-08-09
---

prev

тип: boolean | string | { link?: string; label?: string }

Переопределяет глобальную опцию pagination. Если указана строка, будет заменен сгенерированный текст ссылки, а если указан объект, будут переопределены и ссылка, и текст.

src/content/docs/example.md
---
# Скрываем ссылку на предыдущую страницу
prev: false
---
src/content/docs/example.md
---
# Переопределяем текст ссылки на предыдущую страницу
prev: Продолжить обучение
---
src/content/docs/example.md
---
# Переопределяем ссылку и текст предыдущей страницы
prev:
link: /unrelated-page/
label: Загляните на другую страницу
---

next

тип: boolean | string | { link?: string; label?: string }

То же самое, что и prev, но для ссылки на следующую страницу.

src/content/docs/example.md
---
# Скрываем ссылку на следующую страницу
next: false
---

pagefind

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

Установите, должна ли эта страница быть включена в поисковый индекс Pagefind. Установите значение false, чтобы исключить страницу из результатов поиска:

src/content/docs/example.md
---
# Скрываем эту страницу из поискового индекса
pagefind: false
---

draft

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

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

src/content/docs/example.md
---
# Исключить эту страницу из производственных сборок
draft: true
---

тип: SidebarConfig

Управление отображением этой страницы в боковой панели при использовании автогенерируемой группы ссылок.

SidebarConfig

interface SidebarConfig {
label?: string;
order?: number;
hidden?: boolean;
badge?: string | BadgeConfig;
attrs?: Record<string, string | number | boolean | undefined>;
}

label

тип: string
по умолчанию: title страницы

Устанавливает метку для этой страницы в боковой панели при отображении в автогенерируемой группе ссылок.

src/content/docs/example.md
---
title: Об этом проекте
sidebar:
label: О сайте
---

order

тип: number

Управляйте порядком этой страницы при сортировке автоматически созданной группы ссылок. Страницы с меньшим значением параметра order отображаются выше в группе ссылок.

src/content/docs/example.md
---
title: Страница, которая будет отображаться первой
sidebar:
order: 1
---

hidden

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

Запрещает включать эту страницу в автоматически создаваемую группу боковой панели.

src/content/docs/example.md
---
title: Страница, которую нужно скрыть из автоматически созданной боковой панели
sidebar:
hidden: true
---

badge

тип: string | BadgeConfig

Добавьте значок на страницу в боковой панели, если она отображается в автогенерируемой группе ссылок. При использовании строки значок будет отображаться с акцентным цветом по умолчанию. В качестве опции передайте объект BadgeConfig с полями text и variant для настройки значка.

src/content/docs/example.md
---
title: Страница со значком
sidebar:
# Используется вариант по умолчанию, соответствующий акцентному цвету вашего сайта
badge: Новое
---
src/content/docs/example.md
---
title: Страница со значком
sidebar:
badge:
text: Экспериментально
variant: caution
---

attrs

тип: Record<string, string | number | boolean | undefined>

Атрибуты HTML для добавления к ссылке на страницу в боковой панели при отображении в автогенерируемой группе ссылок.

src/content/docs/example.md
---
title: Открытие страницы в новой вкладке
sidebar:
# Открывает страницу в новой вкладке
attrs:
target: _blank
---

Настройка схемы метаданных

Схема метаданных для коллекции контента Starlight docs настраивается в файле src/content/config.ts с помощью помощника docsSchema():

src/content/config.ts
import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({ schema: docsSchema() }),
};

Подробнее о схемах коллекций содержимого читайте в разделе Определение схемы коллекции в документации Astro.

docsSchema() принимает следующие параметры:

extend

тип: Схема Zod или функция, возвращающая схему Zod
по умолчанию: z.object({})

Расширьте схему Starlight дополнительными полями, задав extend в опциях docsSchema(). Значение должно быть схемой Zod.

В следующем примере мы задаем более строгий тип для description, чтобы сделать его обязательным, и добавляем новое необязательное поле category:

src/content/config.ts
import { defineCollection, z } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({
schema: docsSchema({
extend: z.object({
// Делаем встроенное поле обязательным
description: z.string(),
// Добавляем новое поле в схему
category: z.enum(['tutorial', 'guide', 'reference']).optional(),
}),
}),
}),
};

Чтобы воспользоваться преимуществами хелпера image(), используйте функцию, которая возвращает расширение вашей схемы:

src/content/config.ts
import { defineCollection, z } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({
schema: docsSchema({
extend: ({ image }) => {
return z.object({
// Добавляем поле, которое должно разрешаться в локальное изображение
cover: image(),
});
},
}),
}),
};