📚 Документация MODX Revolution (open source)

Сообщество ведёт документацию по экосистеме MODX Revolution: ядро, дополнения и практические гайды.

🌐 Сайт	Ссылка
Русская версия	docs.modx.pro
English	docs.modx.pro/en

📑 Содержание

• Русский
• English
• Структура репозитория
• Локальная разработка
• Советы контрибьюторам
• Полезные ссылки

Русский

🎯 Цель

Любой может внести вклад без отдельной регистрации на стороннем сайте и без запроса прав: достаточно оформить pull request в этот репозиторий (удобнее всего через fork и ветку с изменениями).

Описываем сторонние дополнения и саму систему MODX на русском и английском. Если хотите вести документацию на другом языке — создайте issue в репозитории.

📝 Формат

• Исходники — Markdown на базе VitePress (Vue 3).
• Русские страницы: каталог docs/.
• Английские страницы: каталог docs/en/ — по возможности поддерживайте паритет с русской версией для одного и того же компонента.

Файлы можно читать на GitHub или собрать сайт у себя (см. локальную разработку).

🚀 Публикация

Содержимое репозитория автоматически отображается на docs.modx.pro после принятия изменений в основную ветку.

🤝 Для контрибьюторов

Пошаговые инструкции, оформление PR и работа с Git — в разделе «Начало работы» на сайте документации.

---

English

🎯 Purpose

Anyone can contribute without signing up elsewhere or asking for access: open a pull request (fork + feature branch is the usual workflow).

We document third-party extras and MODX itself in Russian and English. If you want to maintain docs in another language, please open an issue.

📝 Format

• Sources are Markdown built with VitePress (Vue 3).
• Russian content: docs/.
• English content: docs/en/ — when possible, keep RU/EN in sync for the same component.

You can read files on GitHub or run the site locally (see Local development).

🚀 Published site

The docs from this repo are published at docs.modx.pro/en automatically after merges to the default branch.

🤝 For contributors

See Getting started on the documentation site.

📁 Структура репозитория / Repository layout

Краткая карта (главное для правок в текстах):

Путь	Назначение
docs/components/	Документация дополнений (RU) — основной объём материалов
docs/en/components/	То же на английском
docs/system/	Ядро MODX, xPDO и смежные темы (RU)
docs/en/system/	Системная документация (EN), где есть перевод
docs/guide/	Гайды для авторов и обзор проекта (RU)
docs/en/guide/	Guides (EN)
docs/faq/	Вопросы и ответы
.vitepress/	Конфигурация VitePress, тема, сайдбары
plop-templates/	Шаблоны для генерации новых страниц
scripts/	Вспомогательные скрипты (например, OG-изображения при сборке)

Новую документацию по компоненту удобно начать командой pnpm generate — интерактивный Plop предложит шаблон (одна или несколько страниц) и языки RU/EN.

🔧 Локальная разработка / Local development

Требования: Node.js 22.18+. В репозитории зафиксирован менеджер пакетов pnpm (см. package.json → packageManager); установите pnpm 10 или новее, и он сам переключится на эту версию. Настройки pnpm — в pnpm-workspace.yaml.

pnpm не ставит версии пакетов моложе суток (minimumReleaseAge) и при pnpm add/pnpm update молча берёт предыдущую, даже с @latest. Если свежая версия нужна срочно (например, исправление уязвимости), укажите её явно: pnpm add пакет@X.Y.Z --config.minimumReleaseAge=0. До истечения суток CI и деплой с таким pnpm-lock.yaml не пройдут.

pnpm install
pnpm dev

Сайт откроется в режиме разработки (точный URL — в выводе терминала, обычно http://localhost:5173).

Команда	Назначение
pnpm dev	Локальный предпросмотр (VitePress dev, hot reload)
pnpm build	Продакшен-сборка (перед сборкой запускается генерация OG; для Node задан лимит памяти — см. скрипт в package.json)
pnpm preview	Просмотр уже собранного статического сайта
pnpm generate:og	OG-картинки компонентов (запускается и в pnpm build). Перерисовываются только изменившиеся, кэш — .vitepress/cache/og; в git картинки (docs/public/og/, og-default.png) не хранятся. pnpm generate:og -- --force перерисовывает всё и заново скачивает логотипы
pnpm lint:changed / pnpm lint	Markdownlint: изменённые строки / все файлы; автоисправление — pnpm exec markdownlint --fix <путь> (pnpm lint:fix — по всему репозиторию)
pnpm spellcheck:changed / pnpm spellcheck	Проверка орфографии (RU и EN): изменённые строки / все файлы
pnpm check:sync:changed	У новых русских страниц есть английские версии (заготовка — node scripts/sync-docs-en.mjs <путь>); предупреждение, если изменена только русская
pnpm check:structure:changed / pnpm check:structure	Разделов ##/### в EN не меньше, чем в RU: изменённые страницы (предупреждения, как в CI) / все страницы
pnpm generate	Мастер создания заготовок документации (Plop)

💡 Советы контрибьюторам / Contributor tips

• ✅ Мелкие PR проще и быстрее ревьюить: одна тема (один компонент, один раздел) вместо «всего сразу».
• ✅ Перед отправкой PR прогоните pnpm lint:changed, pnpm spellcheck:changed и pnpm check:sync:changed — их же запускает CI в PR (разметка и орфография — по изменённым строкам).
• ✅ Следуйте структуре соседних статей в том же каталоге: front matter, заголовки, внутренние ссылки VitePress.
• ✅ Скриншоты и схемы кладите в соответствующие папки рядом с документацией или в docs/public/, если так принято для вашего раздела — ориентируйтесь на существующие статьи.
• ✅ Не знаете, с чего начать? Откройте Issues — там можно обсудить идею до большого объёма правок.

🔗 Полезные ссылки / Links

• Репозиторий GitHub
• Issues и обсуждения
• VitePress — документация
• Синтаксис Markdown (оригинал)
• MODX — официальный сайт CMS
• MODX Pro / сообщество — экосистема дополнений и материалов