Данные маршрута

Когда Starlight рендерит страницу в вашей документации, он сначала создаёт объект данных маршрута, чтобы представить содержимое этой страницы. В этом руководстве объясняется, как генерируются данные маршрута, как их использовать и как настроить, чтобы изменить поведение Starlight по умолчанию.

Полный список доступных свойств см. в «Справочнике по данным маршрута».

Что такое данные маршрута?

Данные маршрута в Starlight — это объект, содержащий всю информацию, необходимую для рендеринга отдельной страницы. Он включает сведения о текущей странице, а также данные, сгенерированные на основе вашей конфигурации Starlight.

Использование данных маршрута

Все компоненты Starlight используют данные маршрута, чтобы определить, что рендерить на каждой странице. Например, строка siteTitle используется для отображения заголовка сайта, а массив sidebar — для рендеринга глобальной боковой навигации.

Вы можете получить доступ к этим данным через глобальный объект Astro.locals.starlightRoute в компонентах Astro:

---
const { siteTitle } = Astro.locals.starlightRoute;
---

<p>Заголовок этого сайта — «{siteTitle}»</p>

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

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

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

Этот процесс похож на переопределение компонентов, но вместо изменения того, как Starlight рендерит ваши данные, вы изменяете сами данные, которые рендерит Starlight.

Когда настраивать данные маршрута

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

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

Как настроить данные маршрута

Вы можете настроить данные маршрута с помощью специальной формы «мидлвара». Это функция, которая вызывается каждый раз при рендеринге страницы в Starlight и может изменять значения в объекте данных маршрута.

Создайте новый файл, экспортирующий функцию onRequest, используя утилиту defineRouteMiddleware() из Starlight:
src/routeData.ts
```
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware(() => {});
```

Укажите Starlight местоположение файла мидлвара для данных маршрута в astro.config.mjs:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Мой замечательный сайт документации',
      routeMiddleware: './src/routeData.ts',
    }),
  ],
});

Обновите вашу функцию onRequest, чтобы изменить данные маршрута.

Первый аргумент, который получит ваш мидлвар, — это объект context Astro. Он содержит полную информацию о рендеринге текущей страницы, включая текущий URL и locals.

В этом примере мы сделаем нашу документацию более выразительной, добавляя восклицательный знак в конец заголовка каждой страницы.
src/routeData.ts
```
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware((context) => {
  // Получаем запись из коллекции контента для этой страницы.
  const { entry } = context.locals.starlightRoute;
  // Обновляем заголовок, добавляя восклицательный знак.
  entry.data.title = entry.data.title + '!';
});
```

Несколько мидлваров для маршрута

Starlight также поддерживает использование нескольких мидлваров. Установите routeMiddleware как массив путей, чтобы добавить более одного обработчика мидлвара:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Мой сайт с несколькими мидлварами',
      routeMiddleware: ['./src/middleware-one.ts', './src/middleware-two.ts'],
    }),
  ],
});

Ожидание выполнения последующих мидлваров для маршрута

Чтобы дождаться выполнения мидлваров, расположенных позже в стеке, перед выполнением вашего кода, вы можете использовать await для вызова колбэка next(), передаваемого как второй аргумент в вашу функцию-мидлвар. Это может быть полезно, если нужно дождаться выполнения мидлвара плагина перед внесением изменений. Например:

import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware(async (context, next) => {
  // Ожидаем выполнения последующих мидлваров.
  await next();
  // Изменяем данные маршрута.
  const { entry } = context.locals.starlightRoute;
  entry.data.title = entry.data.title + '!';
});