Пропустить до содержимого

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

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

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

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

  1. Добавьте изображение вашего логотипа в директорию src/assets/:

    • Directorysrc/
      • Directoryassets/
        • my-logo.svg
      • Directorycontent/
    • astro.config.mjs
  2. Укажите путь к вашему логотипу у параметра 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,
  },
}),

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

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

  1. Добавьте изображения для каждого варианта в директорию src/assets/:

    • Directorysrc/
      • Directoryassets/
        • light-logo.svg
        • dark-logo.svg
      • Directorycontent/
    • astro.config.mjs
  2. Укажите путь к вариантам вашего логотипа в параметрах 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
---

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

---
# src/content/docs/example.md
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.

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

  1. Добавьте ваши шрифты в директорию src/fonts/ и создайте пустой файл font-face.css:

    • Directorysrc/
      • Directorycontent/
      • Directoryfonts/
        • CustomFont.woff2
        • font-face.css
    • astro.config.mjs
  2. Добавьте объявление @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;
    }
  3. Добавьте путь к вашему файлу 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-файлы, которые можно добавить в ваш проект.

  1. Найдите шрифт, который вы хотите использовать, в каталоге Fontsource. В данном примере будет использоваться шрифт IBM Plex Serif.

  2. Установите пакет для выбранного вами шрифта. Вы можете найти имя пакета, нажав “Install” на странице шрифта Fontsource.

    npm install @fontsource/ibm-plex-serif
  3. Добавьте 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, чтобы добавить свои стили на ваш сайт.