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

Последнее обновление: 14 сент. 2026 г. / Официальная архитектурная спецификация EpoCanvas

На этой странице самые частые задачи кастомизации собраны в справочник вида «выполняй по шагам — и всё получится». Для каждого рецепта указано конкретное место изменений в файлах; перед началом работы полезно ознакомиться с правилами рендеринга и системой компонентов — это поможет не идти по неверному пути.

Рецепт 1: добавление нового документа

Создайте файл .md в каталоге src/content/docs/canvas/ (имя — строчными латинскими буквами с дефисами, например user-guide.md);

В начале файла оформите Frontmatter:

---
title: Руководство пользователя
description: Одной фразой опишите, о чём эта статья; она показывается в результатах поиска и в карточках при репосте.
---

Откройте astro.config.mjs и зарегистрируйте документ в нужной группе массива sidebar:
```
{ label: 'Руководство пользователя', link: '/canvas/user-guide/' }
```
Сохраните, проверьте в локальном предпросмотре, что документ появился в каталоге слева, и выполните pnpm run deploy для публикации.

Если создать файл без регистрации в sidebar, страница будет доступна по прямой ссылке, но не появится в каталоге слева — это самая частая ошибка новичков.

Рецепт 2: добавление кнопки верхней навигации

Откройте src/config/navigation.ts и добавьте элемент в массив navigationConfig:

{
  id: 'blog',
  labelKey: 'nav.blog',
  defaultLabel: 'Блог',
  href: 'https://blog.epocanvas.com',
  isExternal: true,          // внешняя ссылка открывается в новом окне
},

Откройте src/utils/i18n.ts и добавьте переводы для ключа nav.blog на 10 языках;
После сохранения новая кнопка сразу появится в верхней панели; если ссылка внутренняя и должна участвовать в подсветке навигации, настройте для неё функцию match.

Рецепт 3: изменение правил подсветки страницы

Если из-за изменения пути страницы подсветка в верхней панели срабатывает неверно, отредактируйте функцию match соответствующего элемента в navigation.ts:

match: (pathname: string) =>
  pathname === '/canvas/' || pathname.includes('layout'),

Правило: точное совпадение имеет приоритет, includes служит резервным механизмом; диапазоны match у нескольких кнопок не должны пересекаться, иначе две кнопки будут подсвечиваться одновременно.

Рецепт 4: смена фирменного цвета темы

Откройте src/styles/custom.css;

Измените тройку основных переменных одновременно в блоке светлой (:root) и тёмной (:root[data-theme='dark']) темы:

--sl-color-accent: #10b981;      /* основной цвет: кнопки, выделенные элементы */
--sl-color-accent-low: rgba(16, 185, 129, 0.1);  /* светлый фон выделенных элементов */
--sl-color-accent-high: #047857; /* ссылки и выделенный текст */

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

Рецепт 5: замена логотипа

Расположение	Файл	Назначение
Слева в верхней панели	`public/images/logo.svg`	Значок в верхней панели внутренних страниц; путь задаётся в `logo.src` в `astro.config.mjs`
Большое изображение на главной	`src/assets/logo.svg`	Декоративное изображение справа на посадочной странице

Рекомендуется заменить оба файла одновременно. Логотип должен быть в векторном формате SVG; установите logo.replacesTitle в true в astro.config.mjs, чтобы скрыть текст заголовка и оставить только значок.

Рецепт 6: изменение размеров макета

Три основных размера макета собраны в начале src/styles/custom.css:

:root {
  --sl-sidebar-width: 16.5rem;  /* ширина каталога слева */
  --sl-content-width: 60rem;    /* максимальная ширина основного текста */
  --sl-nav-height: 3.5rem;      /* высота верхней панели */
}

Рецепт 7: изменение подсказок поля поиска

Плейсхолдер поля поиска, подсказки кнопок и другие тексты интерфейса берутся из многоязычного словаря в src/utils/i18n.ts. Откройте этот файл и измените строки вида search.placeholder в двухуровневой структуре «язык → ключ строки»:

export const UI_TRANSLATIONS = {
  'zh-CN': {
    'search.placeholder': '搜索文档与指令...',
    // ... остальные строки этого языка
  },
  en: {
    'search.placeholder': 'Search documentation...',
    // ... остальные строки этого языка
  },
  // остальные 8 языков — аналогично
};

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

Рецепт 8: добавление сервисных `<head>`-тегов для подтверждения сайта

При подключении таких сервисов, как Google Search Console или платформа Baidu для вебмастеров, необходимо добавить теги подтверждения в <head>. Откройте astro.config.mjs и дополните массив head в конфигурации Starlight:

head: [
  // существующая конфигурация favicon ...
  {
    tag: 'meta',
    attrs: {
      name: 'google-site-verification',
      content: 'строка подтверждения',
    },
  },
],

После сохранения и повторного развёртывания проверьте сайт кнопкой подтверждения на платформе. Подробнее о настройке поисковых систем после запуска — в разделе SEO и оптимизация производительности.

Общий порядок проверки после изменений

Независимо от вида кастомизации, перед коммитом проверяйте в следующем порядке:

pnpm run dev      # 1. Просмотреть результат постранично в браузере
pnpm exec astro check && pnpm run build   # 2. Проверка типов + полная сборка
pnpm run preview  # 3. Посмотреть собранный сайт и после этого публиковать

Способы публикации описаны в разделе Развёртывание на Cloudflare Pages.