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

Данный сервис связан с нашим GitHub репозиторием. Любые изменения, внесённые в репозиторий сразу же отображаются и на сайте.

Изнутри проект представляет собой VUE приложение, с плагином vitepress который преобразует md разметку в красивый HTML. VitePress также поставляет инструменты, украшающие сухой и строгий стиль md разметки.

Все что вам нужно - изменить текст внутри конкретного *.md файла (или создать новый файл/каталог с файлами по примеру существующих) и прислать Pull Request с вашими изменениями.

Изменить или добавить новый текст можно по-разному. Самый простой способ - сделать это прямо внутри GitHub. В нем достаточно инструментов для работы с текстом. Но проследить за качеством изменений (особенно если вы добавляете визуальное оформление текста) не получится. Нужно разворачивать проект локально на компьютере.

Простой способ внесения изменений в документацию

Наиболее быстрый и простой способ внесения небольших правок - сделать это прямо внутри GitHub.

Информация

У Вас должен быть аккаунт GitHub (простейшая регистрация).

Выберите необходимый вам файл для редактирования в каталоге docs/components/.

Структура документации

Вся документация располагается в каталоге docs.

📦docs
 ┣ 📂components     - документация по компонентам
 ┣ 📂faq            - готовые решения, заготовки для часто повторяемых задач
 ┣ 📂guide          - документация к документации
 ┣ 📂system         - документация по MODX
 ┣ 📂en             - англоязычная версия документации
 ┃ ┣ 📂components
 ┣ 📂public         - логотипы, изображения используемые внутри проекта
 ┗ 📜authors.json   - список авторов

Документация по компонентам в каталоге docs/components устроена следующим образом:

Можно создать один единственный файл с названием компонента и расширением .md, (например ajaxform.md) и разместить всю необходимую информацию в нем.

Можно создать каталог с названием компонента и внутри разместить произвольное количество .md файлов, по теме вашего компонента. В этом случае главным обязательным файлом будет index.md, внутри которого разместятся ссылки на соседние страницы.

Минимальные требования к именованию файлов и папок

Используйте лаконичные имена файлов и папок (пример: не systemniye-nastroyki и не system-settings, а просто settings)

Не используйте кириллицу. Не используйте знаки препинания, кроме дефиса. Да и его только для связки слов. Только нижний регистр слов

Генератор plop

Для тех кто хочет добавить новую документацию компонента в проект интегрирован скрипт генератора plop.

Инструкция по применению

После установки зависимостей, вам нужно ввести в терминале след. команду:
sh
```
pnpm run generate
```
Таким образом вы запустите CLI helper и увидите такую картину. Используя клавиши ↑ и ↓ выберите нужный язык и нажмите Enter:
```
? Выберите язык / Choose language (Use arrow keys)
> Русский
  English
```

Далее вам будет предложено выбрать шаблон документации, их два: Одностраничная и Многостраничная. Выберите нужный и нажмите Enter.

? Выберите язык / Choose language Русский
? Выберите шаблон документации (Use arrow keys)
  Одностраничная документация
> Многостраничная документация

Теперь вам нужно ввести название вашего компонента и также нажать на Enter.

? Выберите язык / Choose language Русский
? Выберите шаблон документации Многостраничная документация
? Введите название компонента │

И наконец вам нужно будет выбрать языковые версии документации. Используя клавиши ↑ и ↓ и нажатием на Пробел вы сможете отметить нужные вам языки. Затем нажмите на кнопку Enter.

? Выберите язык / Choose language Русский
? Выберите шаблон документации Многостраничная документация
? Введите название компонента myFirstComponent
? Выберите языковые версии документации (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
>(*) Русский
 ( ) English

Готово! Вы увидите примерно такой вывод в терминале. Это значит, что скрипт для вас создал структуру из файлов и папок, а вам останется написать документацию для своего компонента.

? Выберите язык / Choose language Русский
? Выберите шаблон документации Многостраничная документация
? Введите название компонента myFirstComponent
? Выберите языковые версии документации Русский
✔  +! 8 files added
-> \docs\components\myfirstcomponent\events.md
-> \docs\components\myfirstcomponent\index.md
-> \docs\components\myfirstcomponent\quick-start.md
-> \docs\components\myfirstcomponent\interface\categories.md
-> \docs\components\myfirstcomponent\interface\items.md
-> \docs\components\myfirstcomponent\snippets\getcategories.md
-> \docs\components\myfirstcomponent\snippets\getitems.md
-> \docs\components\myfirstcomponent\snippets\index.md

Подсказка

Конечно же вы можете изменять структуру, добавлять или изменять файлы и папки по своему усмотрению, скрипт предназначен лишь для быстрого развёртывания шаблонной структуры.

Полезные команды

Из корня репозитория после pnpm install:

Команда	Назначение
`pnpm dev`	Локальный предпросмотр с hot reload (по умолчанию порт из вывода VitePress, часто `5173`)
`pnpm build`	Production-сборка сайта (тяжёлая; нужен достаточный объём памяти для Node)
`pnpm preview`	Просмотр уже собранного статического вывода
`pnpm run lint:changed`	Проверка разметки (markdownlint) в изменённых строках; `pnpm run lint` — по всем файлам; исправить автоматически — `pnpm exec markdownlint --fix <путь>` (`pnpm run lint:fix` исправляет все файлы репозитория)
`pnpm run spellcheck:changed`	Орфография в изменённых строках (RU и EN); `pnpm run spellcheck` — по всем файлам, подробнее — Проверка орфографии
`pnpm run check:sync:changed`	У новых русских страниц есть английские версии; предупреждает, если изменена русская страница, а английская нет
`pnpm run check:structure:changed`	В изменённых страницах английская версия содержит не меньше разделов `##`/`###`, чем русская (только предупреждения); `pnpm run check:structure` — по всем страницам

CI запускает эти проверки в каждом PR, который меняет docs/. Разметка и орфография учитываются только в изменённых строках — старые замечания в остальных строках файла не мешают. Локально :changed-команды сравнивают с origin/master (сначала выполните git fetch; другую базу задаёт CHECK_BASE=origin/<ветка>).

Для новой русской страницы нужна английская, иначе проверка не пройдёт: если перевода пока нет, создайте заготовку командой node scripts/sync-docs-en.mjs docs/путь/к/странице.md — она скопирует страницу в docs/en/ с пометкой TODO. Если вы правите русскую страницу, а английскую — нет, CI выведет предупреждение: проверьте, не нужна ли та же правка в переводе. Если в изменённой странице в английской версии меньше разделов ##/###, чем в русской, CI тоже выведет предупреждение.

Подробнее про разметку и возможности страниц — в гайде по Markdown, VitePress и Frontmatter.

Частые вопросы

Локальный сервер не стартует или падает сборка

Убедитесь, что установлен Node.js 22.18+ (в package.json указано "engines": { "node": ">=22.18" }). Очистка и переустановка зависимостей: удалите node_modules и выполните pnpm install (pnpm-lock.yaml не удаляйте: по нему ставятся зафиксированные версии).

После обновления pnpm в проекте один раз выполните pnpm install в терминале и подтвердите пересоздание node_modules: иначе pnpm run … из редактора или git-хука остановится с ошибкой ABORTED_REMOVE_MODULES_DIR_NO_TTY. Ошибка packages field missing or empty означает, что установлен pnpm 9: обновите его (npm i -g pnpm@latest).

Где править «эту страницу гайда»

Исходники русского гайда — каталог docs/guide/ в репозитории. Англоязычные зеркала — в docs/en/guide/.

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

Простой способ внесения изменений в документацию ​

Рекомендуемый способ внесения изменений в документацию ​

Структура документации ​

Генератор plop ​

Инструкция по применению ​

Полезные команды ​

Частые вопросы ​