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

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

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

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

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

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

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

Информация

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

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

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

Информация

Для рекомендуемого способа работы вам потребуются навыки работы с основными git командами (clone, fetch, add, commit, push), а также установленный на компьютере менеджер пакетов npm или yarn. Знания и навыки работы с VUE не требуются.

Подсказка

Ссылка на пошаговую инструкцию Как правильно отправить Pull Request в чужой проект

1. Зарегистрируйтесь в GitHub если, у вас до сих пор нет там аккаунта.

2. Сделайте форк репозитория.

   

   Внимание

   Если у вас уже есть форк документации, обязательно синхронизируйте его, чтобы забрать самые свежие обновления.

3. Клонируйте ваш форк к себе на компьютер.

   git clone https://github.com/your-fork/Docs.git

4. Рекомендуется создать отдельную ветку, для вносимого изменения. Но это не обязательно.

5. Если вы хотите предварительно просмотреть вносимые изменения локально на компьютере (рекомендуется), установите необходимые зависимости.

   npm

   npm install
   npm run dev

   yarn

   yarn install
   yarn dev

6. Найдите и внесите необходимые изменения в существующий файл документации или создайте новый.

7. Добавьте внесенные изменения в git, создав новый коммит.

   git add .
   git commit -m "new change in my component"
   git push -u origin 999-название-вашей-ветки

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

Вся документация располагается в каталоге 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.

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

1. После установки зависимостей, вам нужно ввести в терминале след. команду:

   npm

   npm run generate

   yarn

   yarn generate

2. Таким образом вы запустите CLI helper и увидите такую картину. Используя клавиши ↑ и ↓ выберите нужный язык и нажмите Enter:

   ? Выберите язык / Choose language (Use arrow keys)
   > Русский
     English
   

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

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

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

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

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

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

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

   ? Выберите язык / 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

   Подсказка

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