mxLocDoc

Просмотр локальной Markdown-документации проекта прямо в менеджере MODX. Документы лежат обычными Markdown-файлами на диске, на том же сервере, что и сайт, и доступны пользователям админки без публикации наружу.

Одна документация на обе версии

Пакет выходит в двух версиях — под MODX 2 (1.x) и под MODX 3 (2.x). Поведение, настройки, навигация, рендер, поиск и языки идентичны; различаются только требования и внутренний слой загрузки:

• MODX 2 — версия 1.x, MODX 2.6–2.8, PHP 7.4.
• MODX 3 — версия 2.x, MODX 3.0–3.2, PHP 8.1+.

Зачем

Проектная документация часто живёт в Markdown рядом с кодом. mxLocDoc показывает её прямо в менеджере MODX, не публикуя файлы наружу и не требуя отдельного сайта-документации, Node или сборки фронтенда.

Что умеет

• Читает Markdown-файлы из локальной папки, заданной системной настройкой.
• Строит левую навигацию из манифеста _sidebar.json или mxlocdoc.json.
• Строит fallback-навигацию по файлам, если манифеста нет.
• Безопасно рендерит Markdown в менеджере (Parsedown в safe mode).
• Отдаёт относительные картинки и разрешённые ассеты через защищённый connector.
• Ищет по документации с кэшированием индекса.
• Поддерживает языковые папки, например en/ и ru/.

Что не входит

• Редактирование Markdown из менеджера.
• Публичный фронтовый вывод документации.
• Таблицы БД для документов или поиска.
• Node, Vite, Vue или отдельный frontend build.

Начало работы

1. Установите mxLocDoc из менеджера пакетов (версия 1.x для MODX 2, 2.x для MODX 3).
2. Создайте локальную папку документации и положите в неё README.md.
3. Укажите путь к папке в системной настройке mxlocdoc.docs_path.
4. Очистите кэш менеджера MODX.
5. Откройте mxLocDoc в меню менеджера.

Рекомендуемая структура

core/components/mydocs/
├── en/
│   ├── _sidebar.json
│   ├── README.md
│   └── guide/
└── ru/
    ├── _sidebar.json
    ├── README.md
    └── guide/

Настройка mxlocdoc.docs_path указывает на родительскую папку:

[[+corePath]]components/mydocs/

Плейсхолдер [[+corePath]] раскрывается в путь к MODX core во время выполнения; простой относительный путь тоже считается относительно папки core. Если внутри корня есть языковые папки, mxLocDoc покажет переключатель языка в менеджере.