Выбор технологий для сайта документации
На этой странице зафиксированы результаты исследования популярных статических фреймворков документации, проведённого 2026-10-12, и окончательное решение по фреймворку сайта документации этого репозитория.
Журнал решений
Заголовок раздела «Журнал решений»| Дата | Решение | Обоснование |
|---|---|---|
| 2026-10-12 (день исследования) | Принять Astro Starlight, мигрировать с VitePress | Starlight по умолчанию не отдаёт клиентский JS, фреймворк-нейтрален и лучше всего соответствует философии этого репозитория «ноль JS во время выполнения»; три дата-управляемые справочные страницы были переписаны как чистые Astro-компоненты, что позволило полностью убрать три зависимости — vue / vitepress / vite; порог Node >= 22.12 приемлем |
| 2026-10-12 (день исследования, предварительная оценка) | Оставить VitePress | На тот момент выгоды от миграции не покрывали затрат — семь сайтов семейства работали на VitePress, а сайт документации этого репозитория был полностью готов. Этот вывод был заменён решением о миграции, принятым в тот же день, и сохранён ниже как историческая запись |
Миграция была выполнена за один раз (Astro-каркас был построен, а все страницы перенесены в рамках одного коммита, чтобы избежать промежуточных небособираемых состояний). Остальные сайты семейства продолжают использовать VitePress; этот репозиторий не требует от семейства унификации; если в будущем семейство решит unifyировать фреймворк, практика Starlight этого репозитория послужит готовым ориентиром.
Итоги исследования (историческая запись на основе данных 2026-10-12)
Заголовок раздела «Итоги исследования (историческая запись на основе данных 2026-10-12)»- Если бы проект начинался с нуля сегодня и без ограничений семейства, лучшей альтернативой был бы Astro Starlight — производительность, фреймворк-нейтральность, ноль клиентского JS по умолчанию, максимальное совпадение с философией репозитория «ноль JS во время выполнения». (Именно это суждение в итоге и привело к решению о миграции выше.)
- VuePress фактически остановился в развитии, не рекомендуется для любых новых проектов (последний пуш в репозитории — 2024-08-07, v2 до сих пор в rc).
- Единственное, за чем имело смысл следить до миграции — VitePress 2.0 (на тот момент тег
nextуказывал на 2.0.0-alpha.20, стадия alpha).
Данные об активности
Заголовок раздела «Данные об активности»Дата сбора данных: 2026-10-12. Данные GitHub получены через api.github.com, количество загрузок npm — статистика за неделю 2026-10-04 – 10-10, номера версий — из dist-tags registry.npmjs.org. Количество звёзд со временем растёт, при цитировании обращайте внимание на свежесть данных.
| Фреймворк | Технологический стек | Звёзд GitHub | Последний пуш в репозиторий | Недельные загрузки npm | Последний стабильный релиз |
|---|---|---|---|---|---|
| VitePress | Vue 3 + Vite | 18.4k | 2026-10-11 | 1 305 159 | 1.6.4 (next: 2.0.0-alpha.20) |
| Docusaurus | React + MDX | 66.5k | 2026-10-10 | 1 504 459 | 3.10.2 |
| Astro Starlight | Astro (фреймворк-нейтральный) | 9.4k | 2026-10-09 | 1 431 284 (сам astro — 7.22M) | astro 7.3.8 / starlight 0.42.6 |
| docsify | Рендеринг JS во время выполнения | 31.5k | 2026-10-11 | 80 727 | 5.0.0 |
| Nextra | Next.js + React | 13.9k | 2026-07-31 | 238 757 | 4.6.1 |
| Fumadocs | Next.js + React | 13.3k | 2026-10-09 | — | — |
| MkDocs Material | Python | 27.6k | 2026-10-02 | PyPI, не применимо | — |
| Sphinx | Python / RST | 8.1k | 2026-10-05 | PyPI, не применимо | — |
| VuePress | Vue + Webpack | 22.7k | ⚠️ 2024-08-07 | 71 177 | 1.9.10 (v2 застряла на 2.0.0-rc.31) |
| Dumi | Umi + React | 3.8k | 2026-09-14 | 20 163 | 2.4.50 |
| Rspress | Rspack + React | 2.3k | 2026-10-10 | 19 631 | 1.47.2 (2.0 beta.21) |
Ключевые показания: VitePress и Docusaurus — единственные представители первого эшелона с месячной аудиторией свыше миллиона; Starlight поднимается на волне самого Astro (7,22 млн) и является третьим полюсом; у VuePress 23 тысячи звёзд, но в репозитории не было коммитов более двух лет, и он фактически вытеснен VitePress.
Плюсы и минусы по эшелонам
Заголовок раздела «Плюсы и минусы по эшелонам»Первый эшелон: VitePress / Docusaurus / Astro Starlight
Заголовок раздела «Первый эшелон: VitePress / Docusaurus / Astro Starlight»VitePress (использовался до миграции; остальные сайты семейства продолжают его использовать)
- Плюсы: однофайловые компоненты Vue можно писать прямо в markdown (именно на этом строились три справочные страницы этого репозитория — токены / контракты компонентов / золотые сценарии); data loaders на этапе сборки (
*.data.ts) идеально подходят для чтения JSON-источника, а в dev-режиме сwatchпо glob дают горячее обновление; Vite dev чрезвычайно быстр; тема по умолчанию работает из коробки и требует почти нулевой конфигурации; богатое китайскоязычное сообщество и материалы. - Минусы: слабая поддержка MDX (вне экосистемы MDX); версионирование документации, i18n и другие Enterprise-возможности нужно строить самостоятельно или искать плагины; глубина кастомизации темы уступает Docusaurus; поиск на локальном индексе, на крупных сайтах работает mediocre.
Docusaurus (продукт Meta, крупнейшая экосистема)
- Плюсы: плагин версионирования документации (сосуществование нескольких версий) и i18n — самые зрелые среди всех фреймворков; экосистема MDX, система плагинов и инъекции в тему (swizzle) прекрасно проработаны; за спиной Meta, долгосрочная поддержка гарантирована.
- Минусы: тяжёлые зависимости на React-стеке, большой размер JS в сборке; много опций и высокая когнитивная нагрузка; его конвейер данных (жизненный цикл
loadContent) для подключения к JSON-источнику более громоздок, чем loader VitePress; в семействе нет прецедентов.
Astro Starlight (фреймворк-нейтральный, эталон производительности; используется в этом репозитории)
- Плюсы: по умолчанию ноль клиентского JS — максимальное совпадение с философией репозитория «ноль JS во время выполнения»; Content Collections дают типобезопасный слой данных; можно смешивать компоненты на Vue / React / Svelte; самый лёгкий результат сборки; документный опыт темы Starlight превосходен (боковая панель, навигация по якорям, встроенный i18n).
- Минусы: Starlight всё ещё 0.x (0.42.6), API может содержать breaking changes; Content Collections рассчитаны на файловый контент (md / mdx), а для чтения внешних JSON вроде
tokens/*.jsonнужно обходить коллекции и подключать их напрямую в.astro-страницах (в этом репозитории проблема решена вызовом модулей codegen непосредственно из frontmatter); в семействе нет прецедентов, вопросы развёртывания / nginx / соглашения о боковой панели пришлось прокладывать самостоятельно (в этом репозитории всё уже пройдено, см. Описание развёртывания).
Второй эшелон: Nextra / Rspress / Fumadocs / Dumi
Заголовок раздела «Второй эшелон: Nextra / Rspress / Fumadocs / Dumi»- Nextra: экосистема Next.js, сильный MDX, красивая документация; но жёстко привязан к Next.js + React, модель развёртывания (SSG / SSR / Edge) отличается от статического хостинга nginx семейства, а контракт содержимого v4 сильно отличается от VitePress. Мотивации для миграции нет.
- Rspress (продукт web-infra-dev из ByteDance): самая быстрая сборка (Rspack), на крупных сайтах с тысячами страниц заметно превосходит VitePress; дружелюбное сообщество мейнтейнеров, говорящих по-китайски. Но экосистема / плагинов меньше всего (20 тысяч загрузок в неделю), а стандартных парадигм data loaders нет — в этом репозитории всего 30 с небольшим страниц, и затраты на обучение ради скорости не оправданы.
- Fumadocs: самый быстрорастущий новичок последних двух лет (13,3k звёзд, всего 2 открытых issue), Next.js + современная дизайн-система, хороший поиск и переключение видов. Так же жёстко привязан к Next.js, а русскоязычных/китайских материалов мало. Стоит добавить в закладки, но вводить сейчас не стоит.
- Dumi: создан для демонстрации библиотек компонентов (live demo, автогенерация таблиц свойств). Этот репозиторий — хранилище токенов для этапа сборки, в нём нет интерактивного UI для демонстрации, так что ключевое преимущество совершенно не задействуется, плюс жёсткая привязка к Umi / React. Однозначно исключён.
Третий эшелон и особые пункты
Заголовок раздела «Третий эшелон и особые пункты»- MkDocs Material / Sphinx (Python-стек): крайне качественная документация, но требуют Python-инструментарий, что не совпадает по экосистеме со стеком Node >= 20 + pnpm + TS этого репозитория — невозможно повторно использовать TS-типы и функции загрузки codegen. Исключены.
- docsify (рендеринг во время выполнения): нет этапа сборки, подключается с CDN, подходит для маленьких документаций в стиле «одностраничный быстрый старт». Но он не генерирует HTML на этапе сборки (слабый SEO, медленный первый экран) и не позволяет запускать data loaders этапа сборки для проверки по схеме (на этой возможности и построены справочные страницы этого репозитория). Исключён.
Посроковое сопоставление с ограничениями репозитория
Заголовок раздела «Посроковое сопоставление с ограничениями репозитория»| Ограничение / потребность репозитория | VitePress | Docusaurus | Starlight | Остальные |
|---|---|---|---|---|
| Единая система с семью сайтами семейства (префиксы nginx / боковая панель / развёртывание) | ✅ используется на остальных сайтах семейства | ❌ пришлось бы прокладывать заново | ✅ в этом репозитории уже пройдено (три контракта nginx продолжают действовать, см. Описание развёртывания) | ❌ |
| Чтение JSON-источника на этапе сборки для рендеринга справочных страниц | ✅ встроенный loader, реализовано | ⚠️ нужен кастомный плагин | ✅ реализовано (прямой вызов load / resolve codegen из frontmatter .astro-страниц) |
⚠️ больше хлопот |
| Один китайский язык, i18n не требуется | ✅ | преимущество не используется | ✅ | — |
| Текст + таблицы + код, без интерактивных демо | ✅ | ✅ | ✅ | ✅ |
| Дух «ноль JS во время выполнения» | ⚠️ runtime JS присутствует (только у сайта, не входит в зону красных линий) | ❌ тяжёлый JS | ✅ ноль JS по умолчанию | — |
| Повторное использование TS-модулей codegen (типы / валидация) | ✅ проверено (с vite ^5.4.21 SSR поддерживает import.meta.dirname) |
✅ | ✅ проверено (astro 7 включает vite 8, SSR поддерживает import.meta.dirname) |
✅ |
Дополнительные два соображения:
- Красная линия «ноль JS во время выполнения» регулирует артефакты
dist/codegen, а не сайт документации. То, что сайт работает на фреймворке во время выполнения, не нарушает никаких красных линий — он полностью изолирован отdist/, а его сборка попадает в.gitignore. Впрочем, после миграции на Starlight сам сайт тоже стал по умолчанию отдавать ноль клиентского JS (только поиск / переключение темы и немного другого интерактива подгружаются по требованию), что ещё больше соответствует духу красных линий. - Преимущества Docusaurus в версионировании документации и i18n в этом репозитории не используются: один язык, одна версия, содержимое следует за codegen — сценария «сосуществование документации по старым версиям токенов» не существует.
Что продолжаем наблюдать
Заголовок раздела «Что продолжаем наблюдать»- Starlight 1.0: репозиторий сейчас зафиксирован на
^0.42.6. На стадии 0.x ещё возможны breaking changes; после выхода 1.0 оценим путь обновления (руководство по миграции Starlight перечислит все изменения). - VitePress 2.0: оценим после перехода в beta. Остальные сайты семейства по-прежнему на VitePress; главные вопросы — производительность сборки и поддержка Vite 7.
- Сигналы к пересмотру решения: Starlight долго не поддерживается или семейный уровень принимает решение унифицировать фреймворк документации (тогда практика Starlight этого репозитория станет готовым ориентиром).
Copyright © 2024-2026 FengMo WenXue