Что это такое
EpoCanvas Docs — официальный проект документации проекта EpoCanvas. Если сказать прямо: этот репозиторий поставляет сами «документы» — весь сайт, который вы сейчас читаете, и есть его готовый продукт. В репозитории нет функционального кода какого-то другого ПО; «продукт», который вы ищете, — это сам сайт документации.
Что значит «проект документации»
У этого термина два значения, и они справедливы одновременно:
- Это руководство. Содержание строится вокруг вопросов «что это, как пользоваться, как доработать, как опубликовать»: как работать с интерфейсом чтения, как писать новые документы, где менять конфигурацию, какая команда развёртывания. У него одна цель — чтобы тот, кто получил EpoCanvas, не искал ответы у коллег, а сделал всё по документации.
- Это и есть работающая система сайтов. Склонируйте репозиторий локально и выполните две команды,
pnpm installиpnpm run dev, — получите точно такой же сайт, как перед вами. Весь код основан на Astro 5 и Starlight и распространяется по лицензии MIT; его можно целиком забрать и переделать в сайт документации своего собственного проекта.
Есть и легко упускаемая особенность: каждую возможность, описанную в этой документации, вы прямо сейчас используете сами. Трёхколоночный макет чтения, полнотекстовый поиск по всему сайту через Ctrl + K, переключение между 10 языками прямо в правом верхнем углу — в документации описаны возможности, реализованные самим этим сайтом; читайте и тут же проверяйте на практике.
Для чего он на самом деле нужен
В зависимости от роли читателя этот проект документации решает три задачи:
| Кто вы | Чем он может помочь | С чего начать |
|---|---|---|
| Читатель, которому нужно просто что-то найти | Узнать, как пользоваться той или иной функцией, как устранить ту или иную ошибку | Поле поиска в верхней панели или полнотекстовый поиск Ctrl + K — прямой переход к нужному разделу |
| Разработчик, который хочет собрать свой сайт документации | Готовый работающий исходный код сайта документации и процесс развёртывания | Обзор продукта → Быстрый старт → Развёртывание |
| Автор, участвующий в написании документации | Чёткие правила: где хранить файлы, как оформлять текст, куда класть изображения, как публиковать | Три раздела в группе «Написание документации и управление контентом» |
Одной фразой: пользователь всё понимает, разработчик всё забирает себе, автор пишет по правилам.
Что входит в этот проект
Боковая панель делится на пять групп, каждая отвечает на свой вопрос:
- Обзор продукта и начало работы: что это такое? Как запустить локально?
- Ключевые возможности и руководства: как именно пользоваться интерфейсом чтения, поиском, многоязычностью, навигацией?
- Написание документации и управление контентом: как писать новые документы? Какие правила оформления и рендеринга Markdown?
- Конфигурация и доработка: где менять заголовок сайта, меню навигации, цвета темы? Как дорабатывать компоненты?
- Публикация и эксплуатация: как публиковать сайт, привязывать домен, заниматься SEO и управлением версиями?
Каждая статья самостоятельна и доступна отдельно, читать всё подряд не обязательно.
Два распространённых недоразумения
Недоразумение первое: «Это руководство к какому-то ПО, надо найти само это ПО». В этом репозитории только исходный код сайта документации, кода другого ПО здесь нет; на самом деле документация описывает использование, доработку и развёртывание самой этой системы сайтов документации.
Недоразумение второе: «Это сайт только для чтения, скачивать его бессмысленно». Как раз наоборот: исходный код полностью открыт на GitHub, локально он запускается двумя командами; использовать его как шаблон и переделать в сайт документации своего проекта — один из изначально задуманных сценариев.
Следующие шаги
- Хотите увидеть полное описание позиционирования продукта, ключевых возможностей и выбора технологий? Читайте Обзор продукта и ключевые преимущества.
- Хотите сразу запустить сайт локально? Читайте Быстрый старт (запуск за 3 минуты).
- Нужно найти ответ на конкретный вопрос? Используйте поле поиска в верхней панели или
Ctrl + Kдля поиска по ключевым словам.