Пример Hagilight

На этой странице используется общий компонент Astro:

© 2026 HagiCode

Плагин Starlight также добавляет этот же компонент в нижний колонтитул.

Открыть сгенерированную страницу 404

Плагин создаёт ленты для каждого языка: английскую RSS-ленту по умолчанию и русскую RSS-ленту для этой страницы.

Общие компоненты

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

Компоненты Astro

Импортируйте компонент во frontmatter страницы Astro или документа MDX, затем используйте его как любой другой компонент:

---
import Copyright from '@hagicode/hagilight/Copyright';
import PromotoBanner from '@hagicode/hagilight/PromotoBanner';
---

<Copyright name="HagiCode" />
<PromotoBanner locale="en-US" />

Компонент продвижения загружает активные кампании из публичной ленты Index. Он использует текущий язык страницы для выбора переведённого текста и возвращается к английскому, когда перевод отсутствует.

Резервный вариант, предоставляемый сайтом

Когда удалённая кампания неактивна, сайт может предложить посетителям собственный локализованный резервный вариант. Сохраняйте текст и назначение актуальными для вашего сайта:

<PromotoBanner
  fallback={{
    id: 'site-news',
    title: 'Что нового на нашем сайте',
    description: 'Читайте последние примечания к выпуску и обновления продукта.',
    ctaLabel: 'Читать новости',
    link: '/news/',
  }}
/>

Резервный вариант необязателен. Без него недоступная кампания не оставляет на странице пустого баннера.

Интеграция Starlight

Плагин @hagicode/hagilight-starlight сохраняет стандартный нижний колонтитул Starlight и добавляет общую информацию об авторских правах. Баннер продвижения включён по умолчанию; отключите его, если сайт хочет сохранить интеграцию колонтитула, но не показывать рекламу:

import hagilight from '@hagicode/hagilight-starlight';

plugins: [hagilight({ promoto: { enabled: false } })]

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

Frontmatter раскрытия ИИ

Демоверсия включает оба раскрытия по умолчанию и использует root в качестве исходного языка. Добавьте необязательные логические поля во frontmatter страницы, чтобы переопределить эти значения по умолчанию:

---
title: Переведённое руководство
isAITranslation: true
isAIAuthor: true
---

Пропущенное поле наследует настройку плагина. Установите поле в false, чтобы скрыть только это раскрытие:

---
title: Руководство без уведомления об авторе ИИ
isAIAuthor: false
---

Эта страница демонстрирует переопределение: переведённая демонстрационная страница en-us наследует оба уведомления. Уведомления о переводе скрыты на исходном языке и ссылаются на исходную страницу, когда она существует. Схема содержимого демоверсии включает необязательные поля Hagilight через aiDisclosureSchema; потребителям нужно такое же расширение схемы, чтобы использовать их.

Поведение баннера

Баннер остаётся у нижнего края области просмотра, пока нижний колонтитул не виден. Когда нижний колонтитул попадает в область просмотра, баннер исчезает и перестаёт перехватывать указатель и клавиатуру. Он возвращается, когда нижний колонтитул покидает область просмотра, если только не был закрыт.

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

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

Примеры Markdown

Эта страница также демонстрирует распространённые шаблоны Markdown, полезные на сайте документации.

Выделение и ссылки

Текст может быть полужирным, курсивом или зачёркнутым. Строчный код, например promoto.enabled, визуально отличается от основного текста. Ссылки могут указывать на Astro или на раздел этой страницы.

Списки

Неупорядоченный список удобен для связанных элементов:

• Компоненты создаются как файлы .astro.
• Пакеты публикуют исходный код для компиляции в Astro.
• Сайты Starlight могут отказаться от баннера продвижения.

Упорядоченные списки хорошо подходят для последовательности:

1. Установите пакеты вместе с Astro и Starlight.
2. Добавьте плагин Starlight в конфигурацию сайта.
3. Соберите сайт и проверьте сгенерированные страницы.

Списки также могут быть вложенными:

• Содержимое пакета
  • Компоненты Astro
  • Переопределения Starlight
• Демонстрационный сайт
  • Конфигурация демо
  • Страницы документации

Цитаты

Держите повторно используемые компоненты независимыми от маршрутов и текстов конкретного сайта.

Потребляющий сайт может предоставить собственный резервный вариант при необходимости.

Блоки кода

Плагин можно явно включить в конфигурации Astro:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Моя документация',
      plugins: [hagilight({ promoto: { enabled: true } })],
    }),
  ],
});

Данные конфигурации JSON можно показать в отдельном блоке:

{
  "promoto": {
    "enabled": true
  }
}

Таблицы

Таблицы делают обязанности пакетов легко обозримыми:

Пакет	Назначение	Основной вход
@hagicode/hagilight	Общие компоненты Astro	Copyright, PromotoBanner
@hagicode/hagilight-starlight	Интеграция колонтитула Starlight	hagilight()

Управление баннером

Управление	Действие
Закрыть	Отклонить текущий набор продвижения
Назад	Показать предыдущую активную кампанию
Вперёд	Показать следующую активную кампанию
Пауза	Остановить автоматическую ротацию

Списки задач

Простой чек-лист может отслеживать изменение документации:

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

Горизонтальная линия

---

Сборка и упаковка

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

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

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

Вопросы и следующие шаги

При использовании Hagilight на сайте, который уже предоставляет собственный колонтитул Starlight, помните, что Starlight разрешает только одно переопределение колонтитула. Встраивайте общий компонент колонтитула в собственное переопределение сайта, а не регистрируйте оба сразу.

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

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