Быстрый старт (запуск за 3 минуты)

Запустить этот сайт документации можно двумя путями — выберите один в зависимости от вашей цели:

• Хотите сразу увидеть работающий сайт: ничего устанавливать не нужно — переходите сразу к разделу Развёртывание в один клик ниже, нажмите кнопку и через две минуты получите собственный адрес;
• Хотите писать документацию и править контент: сначала запустите проект локально по разделу Подготовка, вносите правки и сразу смотрите результат, а когда закончите — опубликуйте командой развёртывания из шпаргалки по командам.

---

Развёртывание в один клик: одно нажатие кнопки и сайт в сети

Кнопки ниже — официальные «кнопки развёртывания» трёх платформ: Cloudflare, Vercel и Netlify. После нажатия откроется мастер развёртывания соответствующей платформы: она сама склонирует этот репозиторий в ваш аккаунт GitHub, затем автоматически выполнит сборку и публикацию в облаке. Понадобится только аккаунт GitHub — устанавливать на компьютер Node.js и pnpm, а также вводить какие-либо команды не требуется.

Развёртывание на Cloudflare (рекомендуется)

После нажатия кнопки мастер работает в три шага:

1. Вход и авторизация: по очереди войдите в GitHub и Cloudflare. У обоих есть бесплатные тарифы; если аккаунта нет — зарегистрируйте его прямо на месте;
2. Клонирование репозитория: Cloudflare автоматически копирует этот репозиторий в ваш аккаунт GitHub; все дальнейшие правки контента вы вносите уже в собственный репозиторий;
3. Проверка конфигурации и развёртывание: в конце мастер покажет страницу настроек; сверив её с таблицей ниже, нажмите Deploy:

Параметр	Что мастер показывает по умолчанию	Что делать
Имя репозитория / имя проекта	Предзаполнено epocanvas-docs	Оставить по умолчанию
Команда сборки	Определяется автоматически как pnpm run build этого репозитория	Оставить по умолчанию
Команда развёртывания	Предзаполнено pnpm run deploy	Заменить на npx wrangler deploy

Осторожно

Команду развёртывания обязательно замените на npx wrangler deploy. Предзаполненная pnpm run deploy — это команда прямой публикации на Cloudflare Pages, которую оставил себе сопровождающий этого сайта; она развёртывается в жёстко заданное имя проекта и в процессе развёртывания по кнопке сразу завершается ошибкой.

При первом развёртывании Cloudflare, не обнаружив в репозитории файла конфигурации Workers, автоматически определит, что это статический сайт Astro, и создаст в вашем репозитории автоматически сгенерированный Pull Request (PR) с конфигурацией — просто смёржите его; после этого каждая отправка изменений будет автоматически собираться и публиковаться. От нажатия кнопки до появления адреса при благоприятном раскладе проходит две-три минуты.

После завершения развёртывания Cloudflare выдаст публичный адрес вида https://epocanvas-docs.<ваш-поддомен>.workers.dev с HTTPS-сертификатом в комплекте. Чтобы использовать собственный домен, в консоли откройте Workers & Pages → ваш проект → Settings → Domains & Routes и добавьте домен. Для сравнения с опубликованным экземпляром: домен Pages по умолчанию https://epocanvas-docs.pages.dev и собственный домен https://docs.epocanvas.com.

Развёртывание на Vercel и Netlify

Если вы привыкли к другим платформам, две кнопки ниже делают то же самое; обе платформы автоматически распознают проект Astro, вручную заполнять какую-либо конфигурацию сборки не нужно:

• Vercel: нажмите кнопку → авторизуйте GitHub → оставьте значения по умолчанию и нажмите Deploy. В итоге получите домен epocanvas-docs.vercel.app; для личных проектов тариф Hobby бесплатный;
• Netlify: нажмите кнопку → подключите GitHub → платформа сама склонирует репозиторий и выполнит первую сборку. В итоге получите домен epocanvas-docs.netlify.app; бесплатного тарифа достаточно.

Заметка

Механизм у всех трёх кнопок одинаков: репозиторий клонируется в ваш аккаунт GitHub и настраивается непрерывное развёртывание по схеме «отправил код — сайт автоматически пересобрался и опубликовался». Выберите одну платформу и пользуйтесь ею, повторное развёртывание не нужно. Сам этот сайт размещён способом прямой публикации на Cloudflare Pages (см. Развёртывание на Cloudflare Pages), и этот путь не зависит от маршрутов через кнопки выше — для статического сайта документации читатель видит одинаковый опыт доступа при обоих способах хостинга.

---

Подготовка

Развёртывание в один клик подходит, чтобы «сначала выложить сайт», но писать и править документацию в итоге приходится локально. Если собираетесь работать над контентом, сначала убедитесь, что на компьютере установлено следующее базовое окружение разработки:

Инструмент	Рекомендуемая версия	Команда проверки	Описание
Node.js	>= 18.20.8 (рекомендуется 20.3+ или 22 LTS)	node -v	Базовая среда для запуска JavaScript и сборки статических страниц
pnpm	>= 9 (в CI используется 10)	pnpm -v	Рекомендуемый пакетный менеджер: быстро устанавливает зависимости и экономит место на диске
Git	Актуальная стабильная версия	git --version	Нужен для получения кода и управления версиями

Совет

Если pnpm на компьютере ещё не установлен, его можно быстро установить глобально через входящий в Node.js npm:

npm install -g pnpm

---

Запуск локально за 3 шага

Шаг 1: клонируйте репозиторий на компьютер

Откройте терминал и выполните следующие команды, чтобы склонировать код проекта и перейти в папку проекта:

git clone https://github.com/shijianus/epocanvas-docs.git
cd epocanvas-docs

Шаг 2: установите зависимости проекта

В корневом каталоге проекта выполните команду установки:

pnpm install

pnpm автоматически скачает необходимые фронтенд-зависимости по pnpm-lock.yaml, включая Astro, Starlight и модуль обработки локальных изображений; обычно это занимает несколько десятков секунд. По завершении установки терминал покажет общее время:

Done in 1m 3.2s using pnpm v9.15.9

Шаг 3: запустите локальный сервер разработки с предпросмотром

Когда зависимости установлены, выполните команду старта:

pnpm run dev

Терминал выведет примерно следующее (при первом запуске зависимости предварительно компилируются, на что уходит несколько секунд):

astro  v5.18.2  ready in 5152 ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose

watching for file changes...

Теперь откройте в браузере http://localhost:4321 — вы увидите весь сайт документации целиком. После сохранения любого файла .md страница в браузере автоматически обновится и покажет свежий контент.

Рисунок: реальный вид страницы http://localhost:4321/canvas/deployment/ — то есть именно той, которую вы сейчас читаете.

---

Шпаргалка по основным командам разработки

При повседневном написании документации и сопровождении проекта в основном используются следующие команды:

Команда	Сценарий применения	Подробное описание
pnpm run dev	Повседневное написание документации	Запускает локальный отладочный сервер с поддержкой горячей перезагрузки (HMR). После изменения любого файла .md браузер автоматически обновляет контент.
pnpm run build	Тестовая сборка	Полностью компилирует статические страницы всего сайта локально и генерирует в каталоге dist/ HTML, CSS и поисковый индекс Pagefind.
pnpm run preview	Предпросмотр артефактов сборки	Локально запускает лёгкий веб-сервер для содержимого dist/, чтобы перед официальной публикацией проверить корректность ссылок и стилей.
pnpm run deploy	Публикация в один клик	Сначала автоматически выполняет build, затем через инструмент Wrangler отправляет dist/ в рабочее окружение Cloudflare Pages.

Полные шаги публикации и способы проверки на рабочем сайте описаны в разделе Развёртывание на Cloudflare Pages.

---

Где находятся основные файлы конфигурации

Если нужно изменить базовую информацию сайта, в первую очередь смотрите следующие файлы:

• Название сайта и меню оглавления: правьте astro.config.mjs в корневом каталоге. Там можно изменить title (заголовок сайта), site (домен рабочей версии) и sidebar (меню оглавления слева).
• Кнопки верхней панели навигации: правьте src/config/navigation.ts. Здесь можно добавлять и убирать верхние кнопки вроде «Главная», «О продукте» и менять их адреса переходов.
• Цвета страниц и стили шрифтов: правьте src/styles/custom.css. Здесь настраиваются цвета темы для светлого и тёмного режимов.
• Добавление нового документа: создайте файл .md прямо в каталоге src/content/docs/canvas/ и зарегистрируйте его в боковой панели; подробности в Руководстве по написанию и форматированию Markdown.

---

Следующие шаги

Когда локальный сервер успешно запущен, можно двигаться дальше:

• Макет страницы и удобство чтения: подробности о макете верхней панели, боковой панели и области основного текста.
• Подробно о правилах рендеринга: разобраться, как Markdown превращается в итоговую страницу, и не наступить на грабли синтаксиса оформления.
• Развёртывание на Cloudflare Pages: опубликовать документацию в интернете и привязать собственный домен.