Перейти к содержимому
Starlight

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

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

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

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

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

    • Директорияsrc/
      • Директорияassets/
        • my-logo.svg
      • Директорияcontent/
        • …
    • 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: 'Документация с моим логотипом',
          logo: {
            src: './src/assets/my-logo.svg',
          },
        }),
      ],
    });

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

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

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

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

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

    • Директорияsrc/
      • Директорияassets/
        • light-logo.svg
        • dark-logo.svg
      • Директорияcontent/
        • …
    • astro.config.mjs

  2. Укажите путь к вариантам вашего логотипа в параметрах 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:

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

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

По умолчанию страницы 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/:

  • Директория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 по умолчанию:

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

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

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

    • Директорияsrc/
      • Директорияcontent/
        • …
      • Директорияfonts/
        • 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, чтобы добавить свои стили на ваш сайт.