Зацени
Интересный контент, который вы хотите подсветить.
Компоненты
Компоненты позволяют легко и последовательно переиспользовать часть пользовательского интерфейса или стиля. Примерами могут служить карточки-ссылки или встраиваемые ролики YouTube. Starlight поддерживает использование компонентов в файлах MDX и предоставляет некоторые общие компоненты для вашего использования.
Узнайте больше о создании компонентов в документации Astro.
Использование компонента
Вы можете использовать компонент, импортировав его в ваш файл MDX, а затем отобразив его как тег JSX.
Они выглядят как HTML-теги, но начинаются с заглавной буквы, соответствующей имени в вашем операторе import:
---title: Добро пожаловать в мою документацию---
import SomeComponent from '../../components/SomeComponent.astro';import AnotherComponent from '../../components/AnotherComponent.astro';
<SomeComponent prop="something" />
<AnotherComponent> Компоненты могут содержать **вложенное содержимое**.</AnotherComponent>Поскольку Starlight работает на базе Astro, вы можете использовать в своих файлах MDX любые компоненты, созданные на поддерживаемом UI-фреймворке (React, Preact, Svelte, Vue, Solid, Lit и Alpine). Узнайте больше об использовании компонентов в MDX в документации Astro.
Совместимость со стилями Starlight
Starlight применяет стандартные стили к вашему содержимому в формате Markdown, например, добавляет отступ между элементами.
Если эти стили конфликтуют с внешним видом вашего компонента, установите класс not-content для вашего компонента, чтобы отключить их.
<div class="not-content"> <p>Стандартные стили Starlight не применены.</p></div>Встроенные компоненты
Starlight предоставляет встроенные компоненты для частых случаев, нужных в документации.
Эти компоненты доступны из пакета @astrojs/starlight/components.
Вкладки
Вы можете отобразить интерфейс с вкладками, используя компоненты <Tabs> и <TabItem>.
Каждый компонент <TabItem> должен иметь label для отображения пользователям.
Используйте дополнительный атрибут icon, чтобы включить одну из встроенных иконок Starlight рядом с меткой.
import { Tabs, TabItem } from '@astrojs/starlight/components';
<Tabs> <TabItem label="Звёзды" icon="star"> Сириус, Вега, Бетельгейзе </TabItem> <TabItem label="Луны" icon="moon"> Ио, Европа, Ганимед </TabItem></Tabs>Вышеуказанный код сформирует следующие вкладки:
Сириус, Вега, Бетельгейзе
Ио, Европа, Ганимед
Синхронизированные вкладки
Синхронизируйте несколько групп вкладок, добавив атрибут syncKey.
Все <Tabs> на странице с одинаковым значением syncKey будут отображать одну и ту же активную метку. Это позволяет вашему читателю выбрать один раз (например, операционную систему или менеджер пакетов) и увидеть, как его выбор отражается на всей странице.
Чтобы синхронизировать связанные вкладки, добавьте идентичное свойство syncKey к каждому компоненту <Tabs> и убедитесь, что все они используют одни и те же метки <TabItem>:
import { Tabs, TabItem } from '@astrojs/starlight/components';
_Некоторые звёзды:_
<Tabs syncKey="constellations"> <TabItem label="Орион">Беллатрикс, Ригель, Бетельгейзе</TabItem> <TabItem label="Близнецы">Поллукс, Кастор А, Кастор Б</TabItem></Tabs>
_Некоторые экзопланеты:_
<Tabs syncKey="constellations"> <TabItem label="Орион">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> <TabItem label="Близнецы">Поллукс b, HAT-P-24b, HD 50554 b</TabItem></Tabs>Вышеуказанный код сформирует следующий HTML:
Некоторые звёзды:
Некоторые экзопланеты:
Карточки
Вы можете отображать контент в блоке, со стилями Starlight, используя компонент <Card>.
Оберните несколько карточек в компонент <CardGrid>, чтобы отображать карточки рядом, когда есть достаточно места.
<Card> требует title и может дополнительно включать атрибут icon, установленный как название одной из встроенных иконок Starlight.
import { Card, CardGrid } from '@astrojs/starlight/components';
<Card title="Зацени">Интересный контент, который вы хотите подсветить.</Card>
<CardGrid> <Card title="Звёзды" icon="star"> Сириус, Вега, Бетельгейзе </Card> <Card title="Луны" icon="moon"> Ио, Европа, Ганимед </Card></CardGrid>Вышеуказанный код сформирует следующий HTML:
Звёзды
Сириус, Вега, Бетельгейзе
Луны
Ио, Европа, Ганимед
Карточки-ссылки
Используйте компонент <LinkCard> для создания заметных ссылок на разные страницы.
<LinkCard> требует атрибута title и атрибута href. По желанию вы можете добавить краткое description или другие атрибуты ссылки, такие как target.
Группируйте несколько компонентов <LinkCard> в <CardGrid>, чтобы отображать карточки рядом, когда есть достаточно места.
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
<LinkCard title="Кастомизация Starlight" description="Узнайте, как сделать ваш сайт на Starlight уникальным с вашим логотипом, шрифтами, дизайном главной страницы и многим другим" href="/ru/guides/customization/"/>
<CardGrid> <LinkCard title="Создание контента в Markdown" href="/ru/guides/authoring-content/" /> <LinkCard title="Компоненты" href="/ru/guides/components/" /></CardGrid>Вышеуказанный код сформирует следующий HTML:
Кастомизация Starlight Узнайте, как сделать ваш сайт на Starlight уникальным с вашим логотипом, шрифтами, дизайном главной страницы и многим другим
Вставки
Вставки полезны для отображения второстепенной информации рядом с основным содержанием страницы.
У <Aside> может быть необязательный атрибут type со значением note, tip, caution, или danger (по умолчанию — note). Установка атрибута title отменяет заголовок, установленный по умолчанию.
import { Aside } from '@astrojs/starlight/components';
<Aside>Стандартная вставка без пользовательского заголовка.</Aside>
<Aside type="caution" title="Осторожно!"> Вставка предупреждения *с* пользовательским заголовком.</Aside>
<Aside type="tip" title="Совет">
Другой контент также поддерживается.
```js// Например, фрагмент кода.```
</Aside>
<Aside type="danger">Никому не сообщайте свой пароль.</Aside>Вышеуказанный код сформирует следующий HTML:
Starlight также предоставляет собственный синтаксис для рендеринга в Markdown и MDX в качестве альтернативы компоненту <Aside>.
Подробную информацию о пользовательском синтаксисе см. в руководстве Создание контента в Markdown.
Код
Используйте компонент <Code> для рендеринга выделенного синтаксиса кода, когда использование блока кода Markdown невозможно, например, для рендеринга данных, поступающих из внешних источников: файлов, баз данных или API.
См. главу Компонент кода в документации Expressive Code для получения полной информации о параметрах, которые поддерживает <Code>.
import { Code } from '@astrojs/starlight/components';
export const exampleCode = `console.log('Это может быть файл или CMS.!');`;export const fileName = 'example.js';export const highlights = ['файл', 'CMS'];
<Code code={exampleCode} lang="js" title={fileName} mark={highlights} />Вышеуказанный код сформирует следующий HTML:
console.log('Это может быть файл или CMS.!');Импортированный код
Используйте суффикс импорта Vite ?raw, чтобы импортировать любой файл кода в виде строки.
Затем вы можете передать эту импортированную строку компоненту <Code>, чтобы включить её на свою страницу.
import { Code } from '@astrojs/starlight/components';import importedCode from '/src/env.d.ts?raw';
<Code code={importedCode} lang="ts" title="src/env.d.ts" />Вышеуказанный код сформирует следующий HTML:
/// <reference path="../.astro/types.d.ts" />/// <reference types="astro/client" />Дерево файлов
Используйте компонент <FileTree> для отображения структуры каталога с иконками файлов и сворачиваемыми подкаталогами.
Укажите структуру ваших файлов и каталогов с помощью неупорядоченного списка Markdown внутри <FileTree>.
Создайте подкаталог с помощью вложенного списка или добавьте / в конец элемента списка, чтобы отобразить его как каталог без определённого содержимого.
Для настройки внешнего вида дерева файлов можно использовать следующий синтаксис:
- Выделите файл или каталог, сделав его имя жирным, например:
**README.md**. - Добавьте комментарий к файлу или каталогу, добавив дополнительный текст после имени.
- Добавьте заглушки файлов и каталогов, используя в качестве имени либо
..., либо….
import { FileTree } from '@astrojs/starlight/components';
<FileTree>
- astro.config.mjs — **важный** файл- package.json- README.md- src - components - **Header.astro** - …- pages/
</FileTree>Вышеуказанный код сформирует следующий HTML:
- astro.config.mjs — важный файл
- package.json
- README.md
Директорияsrc
Директорияcomponents
- Header.astro
- …
Директорияpages/
- …
Шаги
Используйте компонент <Steps> для стилизации нумерованных списков задач.
Это удобно для сложных пошаговых руководств, где каждый шаг должен быть чётко выделен.
Оберните <Steps> вокруг стандартного упорядоченного списка Markdown.
Внутри <Steps> применим весь обычный синтаксис Markdown.
import { Steps } from '@astrojs/starlight/components';
<Steps>
1. Импортируйте компонент в свой MDX-файл:
```js import { Steps } from '@astrojs/starlight/components'; ```
2. Оберните `<Steps>` вокруг элементов упорядоченного списка.
</Steps>Вышеуказанный код сформирует следующий HTML:
-
Импортируйте компонент в свой MDX-файл:
import { Steps } from '@astrojs/starlight/components'; -
Оберните
<Steps>вокруг элементов упорядоченного списка.
Иконки
Starlight предоставляет набор общих иконок, которые вы можете отображать в своем контенте, используя компонент <Icon>.
Каждый <Icon> требует атрибут name и по желанию может включать атрибуты label, size и color.
import { Icon } from '@astrojs/starlight/components';
<Icon name="star" color="goldenrod" size="2rem" />Вышеуказанный код сформирует следующий HTML:
Все иконки
Список всех доступных иконок показан ниже с их соответствующими именами. Кликните по значку, чтобы скопировать код компонента для него.