Встречайте новый сайт документации

Приветствую всех форумчан! Вот и настал тот день, когда спадёт завеса тайны и мы представляем вашему вниманию новый сайт документации docs.modx.pro.

Предыстория

Несмотря на то, что это покажется странным, но всё началось с того, что я решил переписать AjaxForm выпилив из него все зависимости и как вы знаете, результатом этого стал новый компонент FetchIt. Сразу после его тестирования передо мной встала задача написания документации к нему. Первое, что пришло на ум, естественно — всеми нами любимый docs.modx.pro, но вот беда, хоть и сама идея и реализация на момент его выхода была на отличном уровне, он устарел и по моему мнению имел ряд недостатков.

Поэтому я стал искать другое решение и из-за того, что я давно работаю с фреймворком Vue.js, мой взор пал на генератор статичных сайтов VitePress, который под капотом имеет как раз таки Vue.js. Что было дальше — вы в курсе. Я выпустил FetchIt вместе с его документацией, которую оценили не мало людей и она как раз была разработана на нём.

Вот так и началось, я с @Иван Бочкарев взялись за разработку новой документации для сообщества, ставя перед собой задачу сделать классный и удобный сайт, который будет лишён недостатков предыдущей версии. Достаточно лирики — приступим к технической части, а именно к преимуществам.

Быстрая синхронизация

Новый сайт обновляется ~5 минут с момента публикации/изменения исходников в репозитории.
Старая документация синхронизировалась 1 раз в сутки и это могло и приводило к ситуациям, когда автору компонента приходилось ждать пока на сервере не запустится крон скрипт.

Локальная разработка

Хоть и сама организация документаций компонентов реализована наилучшим образом с использованием markdown, но отсутствовала какая-либо возможность увидеть то как будет выглядеть документация до того, как PR будет принят и пока сайт не синхронизирует новые данные.

В новой версии появилась возможность развернуть сайт документации на локальной машине добавлять/редактировать/удалять данные и сразу же видеть всё в режиме реального времени. Вам ничего сложного делать не придётся, всё идёт в коробке. Стоит только установить зависимости и запустить одной командой локальный сервер. Инструкция прилагается.

Сразу же отвечу на вопрос «А как раньше можно?» — Можно. Вы точно также как и раньше, можете просто прислать PR с изменениями и даже через интерфейс сайта github.com.

Подсветка синтаксиса MODX и fenom

Новая документация моими стараниями умеет подсвечивать синтаксис родного MODX парсера и fenom. Чего не реализовали даже в официальной документации docs.modx.com.

Высокая скорость

В отличии от традиционных SSG, новый сайт фактически является одностраничным приложением (SPA), что даёт отличные показатели скорости загрузки. И соответственно навигация по ней происходит без перезагрузки страницы.

Удобство

У старой версии с этим особых проблем не было, но все же новый дизайн (расширенный мной, хорошо продуманной дефолтной темы VitePress) намного лучше и удобнее. Я даже некоторые решения перенял из старой версии.

Плюшки

В новой версии кроме дефолтных элементов используемых в разметке markdown, появился внушительный список возможностей, которые помогут лучше презентовать свою документацию и легче донести информацию до своего читателя. Вот список некоторых из них:

• Кастомные блоки нескольких типов: информация, подсказка, внимание, осторожно или разворачиваемые блоки.
• Фокусировка определенных строк кода
• Возможность отображать изменения в коде (diff)
• Группировка нескольких блоков кода
• И многое другое

Тёмная тема

Ну и тёмная тема, куда же нам без неё.

Раздел «Готовые решения»

В старой документации был такой раздел, но он не пользовался успехом и я считаю, что зря. Убеждён, что он будет полезен сообществу, т.к. у многих участников сообщества в загашнике есть много разных хитростей и готовых решений связанных с MODX и вместо того, чтобы хранить их где-то в другом месте (Например: gist.github.com) будет лучше опубликовать их тут на форуме и продублировать на новом сайте документации в разделе Готовые решения, и для того чтобы другие пользователи могли знать чьё решение помогло им в работе — Вы сможете указать своё авторство.

Хоть и это далеко не все улучшения, думаю будет достаточно для анонса. Тем более у вас есть возможность увидеть всё своими глазами.

Хочу поблагодарить @Василий Наумкин за проделанную работу, в частности за старую документацию, которая сильно помогла в начале моего пути знакомства с MODX, ведь она сопровождала меня при разработке каждого проекта. Также стоит поблагодарить ребят из modstore.pro и modhost.pro за техническую поддержку и за готовность устранять возникающие препятствия.

Отдельно поблагодарю некоего @Баха Волков за то что усердно работал 3 последних месяца и довёл дело до конца, он большой молодец!

— Спасибо!
— Пожалуйста!

Кроме меня и @Иван Бочкарев в разработке участвовали @Николай Савин, @Дима Касаткин (В жарких спорах предлагал и отстаивал ряд полезных идей), @Руслан Алеев.

Предлагаю каждому не стесняться и написать комментарий о том, как сильно docs.modx.pro помог и/или помогает вам в ваших начинаниях, работе и развитии, ведь именно сегодня день, когда ушла эпоха.

Каждому желаю здоровья и мира.

Поддержка

Развитие продуктов сообщества происходит исключительно благодаря Вам друзья!

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

Поддержать нас можно, используя следующие каналы для доната:

• Отправить донат с карты
• Отправить донат на Яндекс. Деньги
• Отправить донат на Qiwi
• Перевод на каспи в Казахстане на номер +7 701 282 77 37

Огромное спасибо, всем кто поддерживает!

Даже небольшие суммы в 100-500 рублей мотивируют нас продолжать работу.