Первоначальная настройка темы

1. Для начала установите все необходимые пакеты командой npm install или pnpm install, затем выполните первую сборку командой npm run build или pnpm build, чтобы убедиться, что всё настроено правильно.
2. Скопируйте сборку Pagefind (поиск по сайту), чтобы она была доступна в среде разработки. Это делается по-разному в зависимости от вашей ОС. Я подготовил несколько команд, которые помогут.
   • Для Windows выполните npm run winsearch
   • Для OSX или Linux выполните npm run osxsearch
3. Далее нужно настроить i18n вашего сайта (один язык или несколько). Просто выполните команду npm run docs:config-i18n и следуйте инструкциям скрипта!
4. Теперь можно настроить сайт по своему вкусу!

Знакомство с кодом

Я подготовил несколько экскурсий по коду, которые помогут познакомиться с кодовой базой. Для их просмотра в VSCode или другой IDE понадобится расширение Code Tour.

Структура кода

Основная часть кода находится в каталоге src/docs. Благодаря этому всю папку легко перенести в существующий проект и добавить функциональность документации за считанные минуты.

Параметры конфигурации

Общая конфигурация сайта задаётся в папке src/docs/config/. Большинство настроек находится внутри отдельных языковых папок, чтобы упростить работу с переводами.

Настройки сайта

Файл src/docs/config/siteSettings.json.ts используется для настройки параметров сайта. К ним относятся, например, включение view transitions, включение анимаций и отображение кнопок копирования ссылки для заголовков документации.

Данные сайта

Файл src/docs/config/[language]/siteData.json.ts используется для настройки данных сайта. Сюда входят название сайта, описание, ссылки на социальные сети и изображение по умолчанию.

Данные навигации

Настройте данные навигации для верхней панели в файле src/docs/config/[language]/navData.json.ts.

Структура боковой панели

Настройте порядок разделов документации в файле src/docs/config/[language]/sidebarNavData.json.ts.

Robots

Чтобы роботы вроде Google видели правильную карту сайта, отредактируйте файл public/robots.txt и укажите домен вашего сайта.

Дополнительные материалы

Общая информация об Astro

Astro ищет файлы .astro или .md в каталоге src/pages/. Каждая страница становится маршрутом на основе имени своего файла.

В каталоге src/components/ нет ничего особенного, но именно туда мы предпочитаем помещать компоненты Astro/React/Vue/Svelte/Preact.

Любые статические ресурсы, например изображения, можно разместить в каталоге public/. Я также часто использую src/assets для изображений, когда применяю Astro assets для их оптимизации.

Команды

Все команды выполняются из корня проекта, в терминале:

Команда	Действие
npm install	Устанавливает зависимости
npm run dev	Запускает локальный dev-сервер на localhost:4321
npm run build	Собирает рабочую версию сайта в ./dist/
npm run preview	Локальный предпросмотр сборки перед публикацией
npm run astro ...	Выполняет команды CLI, например astro add, astro check
npm run astro -- --help	Справка по использованию Astro CLI

Хотите узнать больше?

Загляните в документацию или присоединяйтесь к серверу Discord.