Обзор продукта и ключевые преимущества
EpoCanvas Docs — официальная система сайтов технической документации, созданная специально для open-source экосистемы EpoCanvas. Она построена на современном фреймворке статических сайтов Astro 5 и Starlight и призвана дать разработчикам платформу документации с профессиональной вёрсткой, быстрой загрузкой, удобным поиском и простотой сопровождения.
Будь то руководство пользователя продукта, спецификация API или описание архитектуры системы, EpoCanvas Docs позволяет автору сосредоточиться на написании контента в Markdown, а читателю — получить комфортный и естественный опыт чтения.
Решаемые практические проблемы
В повседневной разработке и техническом письме многие команды при сопровождении документации сталкиваются со следующими трудностями:
- Медленная загрузка страниц и высокое потребление памяти: страницы, создаваемые многими инструментами документации, содержат много исполняемого кода JavaScript; на телефоне или при слабой сети они открываются медленно, а прокрутка длинных статей подтормаживает.
- Неудобная навигация по длинным статьям: на типичных сайтах документации есть только меню слева, и при чтении длинных технических текстов на несколько тысяч слов трудно быстро понять иерархию внутренних подзаголовков текущей статьи.
- Зависимость поиска от внешних сервисов: распространённые облачные поисковые службы вроде Algolia требуют отдельной регистрации аккаунта и настройки ключей краулера, а в интранете без доступа к внешним сервисам полностью перестают работать.
- Неполная многоязычность: многие сайты документации заявляют поддержку нескольких языков, но на деле переведены только кнопки навигации, а основной текст остаётся на исходном языке; бывает и так, что при отсутствии перевода страница просто отдаёт 404, и читателю приходится самому править URL в поисках контента.
EpoCanvas Docs создан именно для решения этих практических проблем.
Обзор ключевых возможностей
Рисунок: реальный вид страницы обзора продукта. Слева — каталог категорий документации, по центру — основной текст, справа — автоматически сформированное оглавление «На этой странице», подсвечивающее текущий раздел при прокрутке.
1. Понятный трёхколоночный интерфейс чтения
- Левая боковая панель навигации: все категории документации сгруппированы по модулям, есть свёртывание по уровням, при переходе между страницами дерево не перескакивает.
- Центральная область основного текста: максимальная ширина текста 60rem, межстрочный интервал 1,68, блоки кода подстраиваются по ширине — при долгом чтении глаза устают меньше.
- Правая панель оглавления: автоматически собирает заголовки
h2иh3статьи и формирует оглавление «На этой странице»; при прокрутке подсвечивается текущая позиция чтения, а клик по любому подзаголовку плавно прокручивает к нему.
2. Поиск в двух режимах: по странице + по всему сайту
- Поиск на текущей странице: введите ключевое слово в поле поиска в верхней панели — все совпадения на странице подсвечиваются сразу, отображается счётчик вида
3/9, а клавишей Enter можно переходить от совпадения к совпадению. - Окно полнотекстового поиска по всему сайту: нажмите
Ctrl + K(на Mac —Cmd + K), чтобы открыть окно глобального поиска; на основе статического индекса Pagefind выводятся все найденные документы с предпросмотром абзацев. - Все поисковые возможности работают локально в браузере и не зависят от серверной части — поиск действует и при размещении в интранете.
3. Полные переводы на 10 языков
- Поддерживаются 10 языков: упрощённый и традиционный китайский, английский, японский, корейский, испанский, французский, немецкий, русский и португальский. Для каждого языка переведены навигация, боковая панель и весь основной текст документации.
- Нажмите кнопку языка в правом верхнем углу, чтобы перейти к той же статье на нужном языке; в URL добавляется языковой префикс (например,
/en/canvas/), страницу можно сразу добавить в закладки или отправить коллегам, работающим на других языках. - Если для отдельной страницы перевод на какой-то язык ещё не готов, эта страница автоматически показывает содержимое на языке по умолчанию (китайском) — ошибки 404 не возникает.
4. Профессиональная типографика Markdown и кода
- Подсветка кода на базе Expressive Code: для блока кода можно задать заголовок с именем файла, подсветить нужные строки и показать diff.
- Встроенная поддержка четырёх цветных выносок (Note, Tip, Caution, Danger) с возможностью задать свой заголовок.
- Поддерживаются распространённые расширения Markdown: таблицы GFM, чек-листы, зачёркивание и другие; полные правила см. в разделе Подробно о правилах рендеринга.
5. Быстрая сборка и бесплатный хостинг
- Статическая компиляция на базе Astro 5: результат сборки — чистые HTML и CSS плюс небольшое количество JS, загружаемого по мере необходимости; полная сборка всего сайта на 10 языков (около 180 страниц) занимает примерно 25 секунд.
- В комплекте готова команда развёртывания на Cloudflare Pages: одна строка публикует документацию в интернете, а HTTPS-сертификат выдаётся автоматически.
Общая архитектура проекта
Чтобы документация оставалась лёгкой и удобной в сопровождении, система разделена по обязанностям на четыре части:
Рисунок: архитектура системы. Автору достаточно сопровождать исходники Markdown — все остальные этапы выполняются автоматически.
- Основа и стили: статическое ядро на базе Astro 5; дизайн-переменные определены в
src/styles/custom.css, светлая и тёмная темы используют один и тот же набор имён переменных. - Управление контентом: все документы хранятся в каталоге
src/content/docs/и пишутся на чистом Markdown (.md) или на MDX (.mdx) с возможностью встраивать компоненты. - Компоненты интерфейса: путём переопределения нативных компонентов Starlight кастомизированы верхняя панель, боковая панель, оглавление страницы и окно поиска.
- Раздача и доступ: результаты компиляции хранятся в каталоге
dist/, размещаются на Cloudflare Pages и отдаются ближайшими узлами глобальной CDN.
Кому подходит
EpoCanvas Docs подходит для следующих сценариев:
- Официальный сайт документации open-source проекта: руководство пользователя, справочник API, описание архитектуры — всё в одном репозитории;
- Внутренняя база знаний команды: полностью статический сайт без зависимости от внешних сервисов; в интранете поиск работает в полном объёме;
- Личная техническая документация в формате блога: пишете только Markdown, не занимаетесь фронтенд-инженерией, публикация — одной командой.
Он не подходит для сценариев, где нужны вход по логину с проверкой доступа, комментарии и взаимодействие, отображение данных в реальном времени, — у чисто статического сайта нет серверной части, для таких задач потребуется отдельный сервис.
Сравнение популярных инструментов документации
| Возможность | EpoCanvas Docs | Docusaurus | VitePress | GitBook (коммерческая версия) |
|---|---|---|---|---|
| Технологическая основа | Astro 5 + Starlight | React 18 | Vue 3 + Vite | Закрытая SaaS-платформа |
| Механизм поиска | Локальный статический индекс Pagefind | Зависимость от облачного сервиса Algolia | Поиск в памяти на Minisearch | Собственный серверный поиск |
| Макет | Три колонки (меню слева + текст по центру + оглавление справа) | Требуется доработка плагинами | По умолчанию две/три колонки | Фиксированные две колонки |
| Способ развёртывания | Прямая публикация на Cloudflare Pages | S3 / Vercel / GitHub | GitHub Pages | Собственный хостинг платформы |
| Независимость и контроль | 100% open-source, исходный код полностью в ваших руках | 100% open-source | 100% open-source | Закрытый код, много платных функций |
Технологический стек и версии
Технологический стек, фактически используемый в текущей версии (за основу взяты артефакты сборки):
| Компонент | Версия | Назначение |
|---|---|---|
| Astro | v5.18.2 | Ядро статического сайта, отвечает за сборку и маршрутизацию |
| Starlight | v0.32.6 | Фреймворк сайта документации, предоставляет каркас макета и обработку контента |
| Expressive Code | Интегрирован в составе Starlight | Подсветка блоков кода, заголовок блока, подсветка строк |
| Pagefind | Интегрирован через @pagefind/default-ui 1.5.2 | Генерация статического поискового индекса на этапе сборки |
| Wrangler | v4.131.0 | Официальный CLI Cloudflare, выполняет развёртывание |
| Окружение | Node.js 18.20.8 / 20.3+ / 22+, pnpm 10 | Локальная разработка и сборка; pnpm run deploy из-за wrangler требует Node.js 22 или новее |
При обновлении зависимостей заодно прочитайте замечания по регрессионному тестированию в разделе Компоненты интерфейса и доработка.
Структура каталогов проекта
Код проекта организован следующим образом, у каждого каталога своя роль:
epocanvas-docs/├── public/ # Каталог статических ресурсов (изображения и векторные иконки кладутся прямо сюда)│ └── images/canvas/ # Скриншоты интерфейса и векторная схема архитектуры├── src/│ ├── components/starlight/ # Кастомные компоненты страницы (верхняя панель, боковая панель, оглавление страницы, окно поиска и т. д.)│ ├── config/navigation.ts # Конфигурация верхней панели навигации (пункты меню добавляются и удаляются здесь)│ ├── content/docs/ # Место хранения файлов Markdown с текстами документации│ │ ├── index.mdx # Целевая страница (landing page) сайта документации│ │ ├── canvas/ # Документы по разделам (упрощённый китайский, язык по умолчанию)│ │ └── en/ ja/ ... # Каталоги полных переводов на остальные 9 языков│ ├── styles/custom.css # Глобальные стили и переменные цветов темы│ ├── utils/i18n.ts # Словарь строк интерфейса и список языков│ └── pages/404.astro # своя страница 404, текст по языку браузера├── scripts/ # сброс кэша, проверки i18n, изображений и якорей, снимки экрана├── astro.config.mjs # Основной файл конфигурации сайта (здесь задаются заголовок, список языков и разделы боковой панели)└── package.json # Конфигурация зависимостей проекта и команд запускаСледующие шаги
- Хотите запустить проект локально? Читайте Быстрый старт (запуск за 3 минуты).
- Хотите узнать подробнее о макете интерфейса и работе с ним? Читайте Макет страницы и удобство чтения.
- Хотите начать писать новую документацию? Читайте Руководство по написанию и форматированию Markdown и Подробно о правилах рендеринга.