Конфигурация сайта и настройка стилей

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

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

1. Основные сведения о сайте (`astro.config.mjs`)

Файл astro.config.mjs в корневом каталоге — главный конфигурационный файл всего сайта документации. Связанные со сведениями о сайте параметры перечислены ниже (в комментариях указано, когда их менять):

export default defineConfig({
  // Домен продакшен-окружения сайта; влияет на SEO-ссылки и генерацию Sitemap
  site: 'https://docs.epocanvas.com',

  integrations: [
    starlight({
      // Заголовок сайта; отображается на вкладке браузера и в верхней панели
      title: 'EpoCanvas Docs',
      // Описание сайта; используется в сниппетах поисковой выдачи
      description: 'EpoCanvas 全栈技术、架构与产品运维指南',

      // Путь к изображению логотипа в левой части верхней панели
      logo: {
        src: './public/images/logo.svg',
        replacesTitle: false, // если true, отображается только логотип без текста заголовка
      },

      // Ссылка на репозиторий GitHub в правом верхнем углу
      social: {
        github: 'https://github.com/shijianus/epocanvas-docs',
      },

      // Точка входа пользовательской таблицы стилей
      customCss: ['./src/styles/custom.css'],

      // Каталог боковой панели (см. следующий раздел)
      sidebar: [/* ... */],
    }),
  ],

  // Таблица переадресации со старых путей, чтобы ссылки не ломались
  redirects: { '/mail': '/canvas/' },
});

2. Как изменить меню каталога слева?

Каталог категорий документации слева управляется массивом sidebar в конфигурации Starlight внутри astro.config.mjs:

sidebar: [
  // Группа 1: обзор продукта
  {
    label: '产品概览与入门',       // название группы
    items: [
      { label: '产品简介与核心价值', link: '/canvas/' },
      { label: '快速上手 (3分钟运行)', link: '/canvas/deployment/' },
    ],
  },
  // Группа 2: можно добавить собственные группы по вашей задаче
  {
    label: '用户指南',
    items: [
      { label: '账号注册与登录', link: '/canvas/login/' },
    ],
  },
];

label: название категории или статьи, отображаемое в боковой панели; оно может отличаться от title во Frontmatter (например, использовать более короткое отображаемое имя);
link: путь доступа к статье; соответствует расположению файла в src/content/docs/.

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

3. Пользовательский фирменный цвет темы (`src/styles/custom.css`)

Все цвета сайта управляются CSS-переменными, определёнными в src/styles/custom.css. В начале файла находятся переменные светлой темы, а блок :root[data-theme='dark'] содержит переменные тёмной темы:

:root {
  /* Основной цвет бренда (светлая тема) */
  --sl-color-accent: #2563eb;
  --sl-color-accent-low: rgba(37, 99, 235, 0.08);  /* светлый фон выделенных элементов */
  --sl-color-accent-high: #1d4ed8;                  /* ссылки и выделенный текст */

  /* Фон страницы и разделительные линии */
  --sl-color-bg: #ffffff;
  --sl-color-hairline: #e2e8f0;
}

:root[data-theme='dark'] {
  /* В тёмной теме используются те же переменные, меняются только значения цветов */
  --sl-color-accent: #3b82f6;
  --sl-color-accent-low: rgba(59, 130, 246, 0.12);
  --sl-color-accent-high: #60a5fa;

  --sl-color-bg: #0b0f19;
  --sl-color-hairline: #1e293b;
}

Например, чтобы заменить основной цвет всего сайта на яркий зелёный, достаточно изменить --sl-color-accent в блоках светлой и тёмной темы на значения серии #10b981 — кнопки, выделенные элементы и ссылки автоматически изменят цвет.

Размеры макета также собраны в начале этого файла:

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

4. Замена логотипа сайта

Подготовьте векторное изображение фирменного логотипа (рекомендуется .svg, также подойдёт чёткий .png);
Перезапишите им файл public/images/logo.svg (большое изображение на главной странице находится в src/assets/logo.svg);
Обновите страницу в браузере — значки в верхней панели и на главной странице заменятся автоматически.