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

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

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

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

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

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

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

export default defineConfig({
	integrations: [
		starlight({
			title: 'Docs With My Logo',
			logo: {
				src: './src/assets/my-logo.svg',
			},
		}),
	],
});

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

starlight({
  title: 'Docs With My Logo',
  logo: {
    src: './src/assets/my-logo.svg',
    replacesTitle: true,
  },
}),

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

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

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

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

starlight({
  title: 'Docs With My Logo',
  logo: {
    light: './src/assets/light-logo.svg',
    dark: './src/assets/dark-logo.svg',
  },
}),

Включить карту сайта

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

// astro.config.mjs

export default defineConfig({
	site: 'https://stargazers.club',
	integrations: [starlight({ title: 'Site with sitemap' })],
});

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

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

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

---
# src/content/docs/index.md

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

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

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

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

---
# src/content/docs/example.md
title: Страница только с заголовками H2 в оглавлении.
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2
---

// astro.config.mjs

defineConfig({
	integrations: [
		starlight({
			title: '',
			tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
		}),
	],
});

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

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

---
# src/content/docs/example.md
title: Страница без оглавления
tableOfContents: false
---

// astro.config.mjs

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

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

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

Вы можете найти полный список поддерживаемых иконок для ссылок в Справочнике по конфигурации. Дайте нам знать на GitHub или Discord, если вам нужна поддержка для другого сервиса!

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

export default defineConfig({
	integrations: [
		starlight({
			title: 'Документация со ссылками на социальные сети',
			social: {
				discord: 'https://astro.build/chat',
				github: '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:

// astro.config.mjs
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/:

Directorysrc/
- Directorycontent/
  - Directorydocs/
    404.md
    index.md
astro.config.mjs

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

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

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

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

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

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

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

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

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

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

/* src/fonts/font-face.css */

@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:

// 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 install @fontsource/ibm-plex-serif
```
```
yarn add @fontsource/ibm-plex-serif
```

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

// 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:

/* src/styles/custom.css */

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

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

/* src/styles/custom.css */

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

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