Что стало с docs.modx.pro?

Привет форум!

В прошлой заметке я рассказывал, что происходит с docs.modx.pro. С тех пор прошло почти три года, и за это время произошло столько всего, что пора рассказать снова.

Немного цифр (по традиции)

Сейчас в документации примерно три «Войны и мира». Правда, у Толстого нет ни одного сниппета, а у нас их хватает.

Каталог компонентов

134 компонента одним списком уже не список, а простыня. Поэтому у каталога появилась нормальная витрина: популярные компоненты, новые, категории как на modstore.pro и поиск по названию и описанию.

Поиск прощает опечатки

Помните рекордсмена прошлой заметки? Слово «плейсхолдер» с шестью вариантами опечаток. Так вот, новый поиск находит нужное, даже если набрать «плейсходер». Проверено.



Работает он на Algolia DocSearch, как документация Vue, Vite и многих других больших проектов. Открывается по Ctrl+K.

MODX или Fenom

Многие примеры в документации написаны в двух вариантах: для парсера MODX и для Fenom. Раньше вкладку приходилось переключать в каждом блоке кода. Теперь достаточно выбрать один раз, и весь сайт покажет примеры в вашем синтаксисе.

Выяснять, что лучше, мы не стали. Пусть каждый читает на своём.

Читать стало удобнее

• Ширина страницы настраивается: кому-то удобнее узкой колонкой, кому-то на весь экран.
• Совместимость: на странице компонента видно, для каких версий MODX и PHP он сделан.
• Схемы и диаграммы теперь рисуются прямо в тексте. Сложный процесс проще один раз показать, чем описывать тремя абзацами.
• Нашли ошибку? Сообщите в один клик, ссылка на страницу подставится сама.

Опечатки. Сезон второй

В прошлый раз проверка орфографии нашла больше 650 опечаток. В этот раз она выдала 2608 замечаний, и я уже приготовился к худшему. Но оказалось, что большая часть вовсе не опечатки: проверка просто не знала нашего жаргона. Слаг, вебхук, эндпоинт, плейсхолдер и ещё 958 верных слов отправились в словарь, остальное исправлено вручную. Итог: ноль.



Самое интересное из найденного:

• Документация спорила сама с собой, как пишется «хеш». «Хэш» проиграл со счётом 49:0.
• «Сетвар» вместо «сервера». Видимо, автор так часто писал {set $var}, что пальцы набрали его сами.
• В слове «Харденинг» пряталась латинская «e». В прошлый раз это была латинская «C», так что буквы из другой раскладки передают привет.
• Нашлась картинка catalog-grid.png, которая на самом деле JPEG. Разоблачена и переименована.

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

Быстрее и легче

Картинки в документации пережал, весят на 22% меньше, а на глаз разницы нет.

Сайт собирается на треть быстрее: было 5 минут 10 секунд, стало 3 минуты 24 секунды. Принятые правки теперь попадают на сайт почти на две минуты раньше.

А у каждого пул-реквеста будет появляться своя ссылка на превью.

Заключение

Отдельное спасибо @Иван Бочкарев, что присматривал за документацией, пока меня не было. И спасибо всем авторам, которые пишут и обновляют документацию своих компонентов. Если у вас есть идеи, чего не хватает сайту, пишите в комментариях.

И последнее. Прошлую заметку, целиком посвящённую опечаткам, я закончил словами «мира надо головой». Проверка орфографии тогда промолчала. Что бы это значило?

Спасибо всем за внимание и мира над головой.

• docs.modx.pro
• Репозиторий на GitHub