Кастомизация Starlight

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

Добавление своего логотипа

Добавление логотипа в заголовок сайта - это быстрый способ добавить индивидуальность на ваш сайт Starlight.

Добавьте изображение вашего логотипа в директорию src/assets/:
- Директорияsrc/
  - Директорияassets/
    my-logo.svg
  - Директорияcontent/
    …
- astro.config.mjs

Укажите путь к вашему логотипу у параметра logo.src в astro.config.mjs:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Документация с моим логотипом',
      logo: {
        src: './src/assets/my-logo.svg',
      },
    }),
  ],
});

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

starlight({
  title: 'Документация с моим логотипом',
  logo: {
    src: './src/assets/my-logo.svg',
    replacesTitle: true,
  },
}),

Варианты логотипа для светлой и тёмной темы

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

Добавьте изображения для каждого варианта в директорию src/assets/:
- Директорияsrc/
  - Директорияassets/
    light-logo.svg
    dark-logo.svg
  - Директорияcontent/
    …
- astro.config.mjs

Укажите путь к вариантам вашего логотипа в параметрах light и dark вместо src в astro.config.mjs:

starlight({
  title: 'Документация с моим логотипом',
  logo: {
    light: './src/assets/light-logo.svg',
    dark: './src/assets/dark-logo.svg',
  },
}),

Включение карты сайта

У Starlight есть встроенная поддержка создания карты сайта. Чтобы включить генерацию карты сайта, укажите ваш URL в качестве site в astro.config.mjs:

export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [starlight({ title: 'Документация с картой сайта' })],
});

Узнайте, как добавить ссылку на карту сайта в robots.txt в документации Astro.

Макеты страниц

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

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

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

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

По умолчанию заголовки <h2> и <h3> включены в оглавление. Укажите уровни заголовков, которые нужно включить на всем сайте, с помощью параметров minHeadingLevel и maxHeadingLevel, в tableOfContents. Переопределите эти значения для отдельных страниц, добавив свойства в метаданные tableOfContents:

Метаданные
Глобальный конфиг

---
title: Страница только с заголовками H2 в оглавлении
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2
---

defineConfig({
  integrations: [
    starlight({
      title: 'Документация с изменённой конфигурацией оглавления',
      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
    }),
  ],
});

Чтобы полностью отключить оглавление, установите параметр tableOfContents в значение false:

Метаданные
Глобальный конфиг

---
title: Страница без оглавления
tableOfContents: false
---

defineConfig({
  integrations: [
    starlight({
      title: 'Документация с глобально отключенным оглавлением',
      tableOfContents: false,
    }),
  ],
});

Ссылки на социальные сети

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

Каждый элемент массива social должен быть объектом с тремя свойствами:

icon: одна из встроенных иконок Starlight, например "github".
label: доступная подпись для ссылки, например "GitHub".
href: URL-адрес ссылки, например "https://github.com/withastro/starlight".

Следующий пример добавляет ссылки на чат Astro в Discord и репозиторий Starlight на GitHub:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Документация с социальными ссылками',
      social: [
        { icon: 'discord', label: 'Discord', href: 'https://astro.build/chat' },
        {
          icon: 'github',
          label: 'GitHub',
          href: 'https://github.com/withastro/starlight',
        },
      ],
    }),
  ],
});

Ссылки редактирования

Starlight может отображать ссылку «Редактировать страницу» в нижней части каждой страницы. Это упрощает для читателя поиск файла, который можно редактировать, чтобы улучшить документацию. Особенно это может помочь open-source проектам, упрощая процесс внесения вклада от сообщества.

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

Примеры:

GitHub: https://github.com/USER_NAME/REPO_NAME/edit/BRANCH_NAME/
GitLab: https://gitlab.com/USER_NAME/REPO_NAME/-/edit/BRANCH_NAME/

Если ваш проект Starlight не находится в корне вашего репозитория, включите путь к проекту в конце базового URL.

В этом примере показана настройка ссылки для редактирования документации Starlight, которая находится в подкаталоге docs/ в ветке main репозитория withastro/starlight на GitHub:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Документация со ссылками для редактирования',
      editLink: {
        baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
      },
    }),
  ],
});

Настройка страницы 404

Сайты на Starlight по умолчанию отображают простую страницу 404. Вы можете настроить это, добавив файл 404.md (или 404.mdx) в директорию src/content/docs/:

Директорияsrc/
- Директорияcontent/
  - Директорияdocs/
    404.md
    index.md
astro.config.mjs

Вы можете использовать другие макеты и настройки страниц Starlight в вашей странице 404. Например, страница 404 по умолчанию использует макет splash и компонент hero в метаданных.

---
title: '404'
template: splash
editUrl: false
hero:
  title: '404'
  tagline: Страница не найдена. Проверьте URL или попробуйте использовать поиск.
---

Отключение стандартной страницы 404

Если вашему проекту требуется полностью настроенный макет 404, вы можете создать маршрут src/pages/404.astro и установить параметр конфигурации disable404Route, чтобы отключить маршрут Starlight по умолчанию:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Документация с пользовательской страницей 404',
      disable404Route: true,
    }),
  ],
});

Пользовательские шрифты

По умолчанию Starlight использует шрифты семейства Sans-Serif, доступные на устройстве пользователя, для всего текста. Это обеспечивает быструю загрузку документации с использованием шрифта, знакомого каждому пользователю, и не требует скачивания больших файлов шрифтов.

Если вам необходимо добавить пользовательский шрифт на ваш сайт Starlight, вы можете настроить шрифты в CSS-файлах или с помощью любой другой техники оформления Astro.

Настройка шрифтов

Если у вас уже есть файлы шрифтов, следуйте руководству по локальной настройке. Чтобы использовать Google Fonts, следуйте руководству по настройке Fontsource.

Настройка локальных шрифтов

Добавьте ваши шрифты в директорию src/fonts/ и создайте пустой файл font-face.css:
- Директорияsrc/
  - Директорияcontent/
    …
  - Директорияfonts/
    CustomFont.woff2
    font-face.css
- astro.config.mjs

Добавьте объявление @font-face для каждого из ваших шрифтов в файл src/fonts/font-face.css. Используйте относительный путь к шрифту в функции url().

@font-face {
  font-family: 'Custom Font';
  /* Используйте относительный путь к шрифту в функции `url()`. */
  src: url('./CustomFont.woff2') format('woff2');
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

Добавьте путь к вашему файлу font-face.css в массив customCss в astro.config.mjs:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Документация с пользовательским шрифтом',
      customCss: [
        // Относительный путь к вашему CSS-файлу с @font-face.
        './src/fonts/font-face.css',
      ],
    }),
  ],
});

Настройка шрифта из Fontsource

Проект Fontsource упрощает использование шрифтов Google Fonts и других open-source шрифтов. Проект предоставляет npm-пакеты, для использования шрифтов, которые вас интересуют, и включает готовые CSS-файлы, которые можно добавить в ваш проект.

Найдите шрифт, который вы хотите использовать, в каталоге Fontsource. В данном примере будет использоваться шрифт IBM Plex Serif.
Установите пакет для выбранного вами шрифта. Вы можете найти имя пакета, нажав «Install» на странице шрифта Fontsource.
- npm
- pnpm
- Yarn
Окно терминала
npm install @fontsource/ibm-plex-serif
Окно терминала
pnpm add @fontsource/ibm-plex-serif
Окно терминала
yarn add @fontsource/ibm-plex-serif

Добавьте CSS-файлы Fontsource в массив customCss в astro.config.mjs:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Документация с пользовательским шрифтом',
      customCss: [
        // Файлы Fontsource для regular и semi-bold шрифтов.
        '@fontsource/ibm-plex-serif/400.css',
        '@fontsource/ibm-plex-serif/600.css',
      ],
    }),
  ],
});

Fontsource предоставляет несколько CSS-файлов для каждого шрифта. См. документацию Fontsource по включению различных начертаний и стилей, чтобы понять, какие использовать.

Использование шрифтов

Чтобы применить шрифт, который вы настроили для вашего сайта, используйте имя вашего выбранного шрифта в CSS-файле. Например, чтобы заменить шрифт по умолчанию везде, установите пользовательское свойство --sl-font:

:root {
  --sl-font: 'IBM Plex Serif', serif;
}

Вы также можете написать более точные стили CSS, если хотите применить ваш шрифт более выборочно. Например, чтобы установить шрифт только для основного контента, но не для боковых панелей:

main {
  font-family: 'IBM Plex Serif', serif;
}

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