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

Приветствую всех форумчан! Вот и настал тот день, когда спадёт завеса тайны и мы представляем вашему вниманию новый сайт документации 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, появился внушительный список возможностей, которые помогут лучше презентовать свою документацию и легче донести информацию до своего читателя. Вот список некоторых из них:


Тёмная тема


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

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


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

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

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

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

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

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

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

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

Поддержка


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

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

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

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

Даже небольшие суммы в 100-500 рублей мотивируют нас продолжать работу.
Баха Волков
18 июня 2023, 22:02
modx.pro
3
1 243
+43

Комментарии: 19

Иван Бочкарев
18 июня 2023, 22:09
+7
@Баха Волков Огромное спасибо тебе! Без тебя так круто не получилось бы!
    Баха Волков
    18 июня 2023, 22:16
    +5
    Тебе спасибо, что начал и зарядил меня!
    Артур Шевченко
    18 июня 2023, 22:10
    +7
    Так посмотришь на новую документацию и кажется, что у Modx есть будущее)))
      Николай Савин
      18 июня 2023, 22:21
      +11
      Да покоится с миром старый сайт, который воспитал наверное 90% всех присутствующих. @Баха Волков ты проделал колоссальную, титаническую работу — низкий поклон тебе.
        Руслан Алеев
        18 июня 2023, 22:41
        +3
        Огненная мощь, спасибо!
          Сергей Карпович
          18 июня 2023, 22:52
          +3
          Спасибо ребята за ваш труд
            Алексей Смирнов
            18 июня 2023, 23:39
            +4
            Да, ушла в прошлое эпоха старого сайта с докой. Ее «затер я до дыр». Она научила меня читать и писать по MODX-овски и переводить на другие языки. )) Громадное спасибо за это @Василий Наумкин
            Сейчас буквально ношусь по новой доке, чудесно! Скорость переключения, это прям космос для меня, конечно, статика она такая быстрая. И моя личная неприязнь к возвращающему скролу страницы теперь утилизирована и снова хочется жить! )) Темная тема понравилась, хотя я противник темной темы, но вот очень зашла! Вообще огромное спасибо за проделанную работу. После таких изменений вдохновляешься еще сильнее на свои подвиги!!!
            Спасибо всей команде русского сообщества MODX за то что делаете!
            Отдельное спасибо некоему @Баха Волков, что взял и сделал!
            Так держать, и даже выше!
              Андрей Шевяков
              19 июня 2023, 08:28
              +5
              Очень круто получилось!
              Спасибо за ваш труд! Небольшая Благодарочка улетела на донат.
                Dan
                Dan
                19 июня 2023, 09:06
                +4
                Шикарная работа, спасибо вам за активное развитие сообщества!
                Думаю остальные будут рады финансово поддержать такие огромные старания!
                  Алексей
                  19 июня 2023, 09:56
                  +5
                  Спасибо, за ваш труд! Донат ушел.
                    Vladimir
                    19 июня 2023, 09:59
                    +4
                    Спасибо вам огромное! Донат уже на каспи
                      Здоров Александр
                      19 июня 2023, 10:42
                      +5
                      Огонь! Приятное удивление было сегодня, когда из закладок открыл страницу и… визуальный кайф от темной темы, подсветка синтаксиса modx. постоянно сижу на документации (хотя уже большую половину синтаксиса помню наизусть). сайт помог начать делать сайт быстрее и делать меньше ошибок.

                      вижу идеальный стандарт документации для фирмы и команды (сочетание файлового сайта и markdown)!

                      огромное спасибо всем причастным!
                        Руслан Алеев
                        19 июня 2023, 13:03
                        +5
                        Если подумать, то разработка доки чаще сложнее разработки компонента/проекта =)
                        Низкий вам поклон @Василий Наумкин @Баха Волков @Иван Бочкарев, что у нас есть не только дока популярных компонентов, но и функционал добавления документации.
                          Дима Касаткин
                          19 июня 2023, 15:51
                          +8
                          Очень крутое обновление! Не смотря на то, что он теперь он не на MODX, а вообще статический (т.е. набор html-файлов и скриптов без классического движка), считаю для документации это отличное решение, к тому же она стала ещё future-proof, как теперь принято говорить, их-за возможности держать локально полнофункциональную копию, что особенно важно в нынешние времена, когда даже stackoverflow иногда перестаёт открываться…

                          А дополнительные возможности разметки и подсветка синтаксиса MODX + Fenom это просто здорово! Уверен что авторы документации оценят и через какое-то время мы начнем встречать всё больше этих фишек со спец. разметкой даже в привычных разделах!

                          Старый сайт документации тоже был не плох, но заметно уже устарел. Хотя отмечу, что некоторые моменты на новом заметно отличаются (например навигация по breadcrumbs) и по началу это может быть не привычно. Но в целом стало намного лучше. Большая и впечатляющая работа! Спасибо за неё, и за то, что находите возможным рассматривать обратную связь ;)

                          Ещё очень здорово, что даже редиректы со старой версии сделали, проверял руками множество ссылок из чата сообщества, битых не нашлось — репект!
                            Константин Ильин
                            19 июня 2023, 16:06
                            +4
                            Присоединяюсь ко все похвалам!) красота!
                            только наварено размер шрифта контентной части кажется лучше 14px
                              Павел Голубев
                              19 июня 2023, 18:30
                              +4
                              Спасибо, ребята. Афигенно вышло!
                                Ivan
                                20 июня 2023, 11:30
                                0
                                Сайт не работает
                                Антон Тарасов
                                21 июня 2023, 11:20
                                +6
                                Низкий вам, ребята, поклон за такую стильную, вкусную и функциональную имплементацию документации!
                                Очень она нужна и крайне важна. И выручала не раз, и пуще прежнего будет.

                                Интересно, а наши западные партнеры не желают ли по образу и подобию освежить docs.modx.com?

                                Ну и конечно же искренне задонатил.
                                  Авторизуйтесь или зарегистрируйтесь, чтобы оставлять комментарии.
                                  19