Open Source документация MODX

Хочу предоставить вам наш новый сервис, который позволит полностью решить вопрос с документацией MODX.

Сейчас есть много разных источников: сообщества, официальный сайт, вики и у всех у них есть большие недостатки:

Нужно получить логин и пароль от хозяев сайта
Неудобное редактирование
Далеко не всегда есть контроль версий
Сайт может закрыться в любой момент, и весь твой вклад останется только в кэше гугла

В качестве маленькой иллюстрации: лично я получал пароль для http://rtfm.modx.com через письмо в службу поддержки. Создал там несколько своих страниц с огромным трудом - спасибо их редактору, а потом они перенесли сайт на что-то новое, и мой пароль не подходит!

Просить новый, как вы понимаете, желания нет. А вот организовать качественную документацию, с которой будет удобно работать всем желающим - есть.

И вот мне на глаза попался проект http://daux.io, который генерирует сайт динамически, по статичным страницам. Сами страницы должны быть формата Markdown, и могут храниться где угодно, например в GitHub!

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

Более того, эта документация никому не принадлежит! Она не пропадёт и не исчезнет - каждый может её скопировать и развернуть у себя на сайте. Она хранит все правки, каждую из них можно обсудить. Если вам нечего написать - вы можете исправлять опечатки.

В общем, сплошные плюсы. Но и минусы у реализации в виде daux.io тоже есть: - Неудобное управление шаблоном. Фактически, он вшит прямо в index.php

Отсутствие мультиязычности в оформлении страниц. Сами страницы можно вести на разных языках, а вот отображать даты в разных форматах - никак.
Нет кэширования, неизвестно каких объемов документацию он потянет. А если там 5000 документов, это при каждом запросе нужно сканировать всё дерево, чтобы сгенерировать меню?
Нет встроенного поиска. Конечно, Google поможет, но когда еще он проиндексирует сайт, и насколько хорошо?
Нет перенаправления с одного адреса на другой, при переносе документа. А вдруг кто-то ошибся в имени файла?
Довольно много ошибок в коде: 80 закрытых и еще 20 открытых. И это на проект, с двумя основными php файлами.

В общем, хорошенько подумав, я написал свой скрипт для сборки сайта MODX из статичных страниц markdown. Теперь у нас есть все плюсы, и никаких минусов.

Вот что у меня получилось - http://docs.simpledream.ru. Пример заполненной страницы - вот. Шаблон работает на третьем Bootstrap, проверил всё на мобильниках и планшетах - проблем нет, читать приятно.

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

Следующий этап - это разработка api для встраивания текстов с сайта на другие ресурсы. Чтобы вы писали в одном месте, а пользоваться можно было где угодно. Может, даже какие-то короткие ссылки приделаю, чтобы было удобно посылать всех читать =)

Надеюсь, идея приживётся и у нас наконец-то появится хорошая документация для MODX Revolution! Очень надеюсь на вашу помощь в наполнении. Как говорится, плиз retweet.

71 комментарий

Чикин Артур

Круто, Просто круто)

Василий Наумкин

Документацию может писать любой желающий - нужен только аккаунт на GitHub. Заходишь в нужный файл, жмешь edit и отправляешь мне. Дальше я принимаю твои изменения (возможно, что-то редактирую) и выгружаю на сайт.

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

Чикин Артур

Да) Просто статью прочитал немного не вьехал а потом главную Доков и уже стало понятно)

Я так понимаю документацию будем вести преимущественно на русском языке, для своих? Или на ломаном английском тоже?)

Василий Наумкин

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

Переводить по готовому будет всяко проще. В любом случае, если кто пришлёт коммит на английском - добавлю его в соответствующую ветку.

Scorp Satex

Класс! Именно этого не хватало!

Очень хотел бы там увидеть раздел "Примеры". А еще лучше пошаговые инструкции... Можно и видео встроить. :)

А то часто приходится клиентам делать видео-касты показывая как в минишопе заполнять например товары.

Василий Наумкин

Будет, со временем, можешь и сам добавить =)

Чикин Артур

С такими темпами скоро у нас будет свой форк MODX Revo с своими блэкджеком и шлюхами.

Репозиторий есть. Документация теперь своя.

Что еще нужно для полного счастья?)

Василий Наумкин

Зачем форк?

Мы просто выстраиваем работу MODX в России, ибо среди авторов никто не говорит по-русски и за нас этого не сделает.

Alex Vakhitov

Классное начинание. Мне для открытой документации наравится readthedocs.org, ну а если хочется все хранить у себя то конечно sphinx-doc

Александр Степанов

Василий, это прекрасно! Идея просто чудо :)

Чикин Артур

У меня такой вопрос, если понадобится например в документации выводить картинки или иллюстрации как быть? Где будем их хранить?

Может их конвертировать в base64 images и хранить прям в git? Иди это будет не правильно?

P.S Прислал первый коммит.

Василий Наумкин

Принял и добавил первый коммит.

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

Возможно, это будет отдельной веткой в репозитории, а все ссылки на изображения будут автоматически заменяться - позже подумаем еще. Base64 хранить как-то не хочется.

Чикин Артур

А где можно посмотреть подробнее про синтаксис файлов md?

Как сделать табличку?

И я не могу понять как синхронизировать форки? Я получается делаю в своем и отправляю реквесты. Но не знаю что уже было добавлено а что нет.

Василий Наумкин

На главной странице ссылка на документацию http://daringfireball.net/projects/markdown/syntax В markdown можно использовать html, а значит таблицы можно писать тегами.

По репозиториям ответ здесь. Можно не заморачиваться и удалять\ создавать форк каждый раз. Других способов я не знаю, но наверное, можно нагуглить.

Alex Vakhitov

Инструкция от самого гитхаба как синхронизировать форки

Виталий Киреев

А на самом гитхабе это можно провернуть?

Alex Vakhitov

Сам всегда из консоли это делал, поэтому не знаю. Но скорей всего нет

Чикин Артур

Добавь в расширения какой нибудь wysiwyg Markdown редактор для того что бы онлайн посмотреть можно было перед отправкой коммита в документцию.

Например нашел: markitup

Василий Наумкин

В какие расширения, о чем ты?

Markdown для того и нужен, чтобы работать без редакторов. Готовый файл показывает сам GitHub, например вот.

Чикин Артур

У тебя есть раздел Утилиты Туда бы добавить редактор в котором можно было бы сделать пред просмотр генерируемого документа. markitup поддерживает язык и имеет возможность пред просмотра.

Василий Наумкин

В утилиты уже добавляю, только без markitup - там по другому всё работает.

Чикин Артур

Ну я только предложил как вариант)

Василий Наумкин

Держи http://bezumkin.ru/utils/markdown

Чикин Артур

На гит хабе поддерживается табличка вот так:


Имя      | Возраст
---------|:-------:
Анна     |   29
Дмитрий  |   47
Федор    |   32

У тебя вроде как нет(

Василий Наумкин

У меня, вроде как, и не GitHub?

А там есть кое-какие изменения.

Василий Наумкин

Таблицы в Markdown Extra, а у меня пока обычный.

Попробую прикрутить попозже.

Василий Наумкин

Прикрутил, таблицы теперь тоже работают.

Александр Наумов

Гениально!!! Очередной весомый вклад Василия в развитие MODX.

Денис А.

Огромное спасибо, Василию и студии SimpleDream. Хорошо что есть такие люди в сообществе MODx!!!

Василий Наумкин

На здоровье!

Виталий Батушев

Вась, а можно ли будет эту документацию конвертнуть под Dash? Тем более что есть Windows/Linux клиент, который читает Dash-овые docset-ы?

Василий Наумкин

Если он умеет читать markdown - конечно. Это же просто набор директорий и файлов в определённом формате.

К тому же, markdown очень легко конвертируется в HTML - можно и его попробовать загнать в Dash.

Чикин Артур

Баг в markdown!

Если использовать конструкцию вида:

[[MinifyX? &minifyCss=1 &minifyJs=1 &cssSources= assets/templates/himyf/css/normalize.css, assets/templates/himyf/css/foundation.css, assets/templates/himyf/css/font-awesome.css, assets/templates/himyf/css/app.css &jsSources= assets/templates/himyf/js/foundation.js ]] [[+MinifyX.css]] [[+MinifyX.javascript]]

То все зависает и перестает отвечать, если вызывать так:

То все нормально.

Василий Наумкин

Нет, это не в markdown баг =)

Починил.

Чикин Артур

Теперь перестали отображаться ссылки. Не работает :

[Cсылка](http://bezumkin.ru)

[![Картинка 1](image/84ee5485-22bd-58ba-b7c7-f2f51dcded44)](image/61ba0da7-e5a6-5bd7-bfef-fa27ad3bb370)

Василий Наумкин

Всё поправил.

Чикин Артур

Я его видел! Видел! Новый редактор!!:))

Scorp Satex

Какая-то беда с картинками в статьях.

Пытаюсь вот тут открыть картинку любую: http://docs.simpledream.ru/components/hybridauth/providers/facebook

Вместо этого в pop окне совсем другое.

Василий Наумкин

Поправил.

Чикин Артур

Нужно немного поправить верстку и заменить:


footer {
    position: absolute;
    bottom: 0;
    left: 0;
    padding: 10px;
    border-top: 1px solid #E3E3E3;
    background: #F5F5F5;
    width: 100%; }

На


footer {
    position: relative;
    bottom: 0;
    left: 0;
    padding: 10px;
    border-top: 1px solid #E3E3E3;
    background: #F5F5F5;
    width: 100%; }

Scorp Satex

А будет раздел куда слать запросы по документации? А раздел пошаговых инструкций будет?

Мне вот очень интересно было бы узнать как правильно настроить права доступа для менеджера на miniShop2. Я сам уже делал это несколько раз, но всегда какие-то грабли были.

Василий Наумкин

Никуда не слать, каждый добавляет, что хочет - по желанию и наличию времени.

Вот ты разберись с разрешениями (там их всего 2: mscategory_save и msproduct_save), напиши заметку, да пришли в репозиторий, чтобы все могли прочитать.

Чикин Артур

Вот документация (информация) нужна всем, но многие сделав что то забывают делится этим.

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

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

Чикин Артур

Еще бы поиск по документации сделать. Было бы совсем кайф:)

Василий Наумкин

Будет, конечно, через mSearch2.

Виталий Киреев

Попробовал добавить. Почему-то форкнулись не все компоненты. Еще, когда компонентов станет много, будет неудобно без сортировки по алфавиту. Сейчас кажется сортирует по номеру в файле.

Василий Наумкин

Будет поиск, ну и независимо от того, как импортируется, я могу выводить на сайте по разному.

Сделал по алфавиту.

Чикин Артур

Почитал комментарии на хабаре и немного смутился.

Не кто Andchir возмущается тем что документация находится на под домене Simple Dream. Что я думаю не так страшно. Пока что чужих компонентов там мало, в основном свои. И не успевает пройти пару комментариев как снова начинается бранство и писькомерство.

Это так печально...

Василий Наумкин

Так и живём.

Разговоров много, а делом занимаются всего несколько человек.

Чикин Артур

Вот именно, тот же Философ больше всех орал про свой быстрый магазин, ни компонента, ни документации которого вообще не видно. Сплошной код, который нужно еще допиливать и допиливать.

Сообщество community.modx-cms.ru как сплошная мусорка. Вопросы про Evo вперемешку с Revo и со статьями. modx.im у них там свой Modx и своя атмосфера, Evo атмосфера.

modx.by там конечно интересного достаточно, но это просто блог, 1 человека. Да там есть зачатки документации. Но там отсутствует всякая социальность. И скорость пополнения документации разочаровывает.

Что касается сайта сообщества, то они вполне могут сделать точно такую же выгрузку из репозитория на свой сайт и точно так же пополнять документацию информацией. Пока что как мне кажется только я один им и занимаюсь, Пару часиков в день и не каждый день:(

Хотя я думаю что для начала сообществу все таки нужно уйти с LS или более здраво продумать аргодинамику. А то там ничего не понятно, разделов нет. Какие то блоги. Чьи блоги. Для чего они?

Василий Наумкин

Да, примерно так всё и обстоит на мой взгляд. И будет обстоять, потому что у всех свои амбиции и обидки. Мы пытаемся подняться немного выше, и дать понятный инструмента на GitHub. Понятно это не всем (см. амбиции и обидки).

В любом случае, я уверен, все получится!

Пока что как мне кажется только я один им и занимаюсь

Нет, не один. Я редактирую твои коммиты, кое-что дополняю и работаю над самим сайтом. Сегодня вот сделал поиск и переключалку языков.

Процесс это не быстрый, но он идёт.

Чикин Артур

Ну ты само собой разумеется, я про остальных. Github говорит что всего 5-теро человек как то попытались изменить документацию. Хотя просмотров про не было уже 59. Хотя Яндекс метрика говорит про 500+

Алексей Карташов

Пошёл прочитать на хабр и что могу сказать - это ппц.

Я не знаю кто такой Andchir и не знаю его заслуг перед сообществом, поэтому возможно (и очень даже может быть) они есть. Но манера ведения диалога - это детский сад и закидывание какашками оппонента без всякой аргументации. Суть:

"A: Твои сниппеты говно, а ты распиарившийся мудак, которые ещё к тому же пиарит SD, а не меня любимого! B: 1. Ок, приведи альтернативы моим сниппетам. 2. Ок, это твоё мнение. A: Твои сниппеты говно, а ты распиарившийся мудак, которые ещё к тому же пиарит SD, а не меня любимого! B: ..."

Есть у нас сайт сообщества, но нет, мы будем грузить документацию Безумкину.

Это вообще даже не знаю как комментировать. "Ты если сделал - молодец. А теперь грузи на сайт НАШего сообщества! Это же дело общее. А мы и дальше будем говорить, какой ты и твои SD самопиарившиеся мудаки.". Он адекватен вообще? Я бы с таким человеком вообще в диалог не вступал - одна желчь, зависть и отсутствие аргументов. Зря только время тратить.

Andchir, я надеюсь вы это прочитаете - смиритесь с тем фактом, что сайт Василия - это новое сообщество. С диктатурой (целиком поддерживаю. Никакой демократии. Только аргументированная диктатура, но это, пожалуй, тема совершенно другого обсуждения), поэтому без присущих ВАШИМ сообществам пафоса и двуличия. С постоянной помощью новичкам, новыми и действительно нужными продуктами. И сформировавшимся ядром хорошей, доброй и лояльной аудитории, которое постоянно увеличивается и становится профессиональней (опять же - это огромная заслуга Василия). Это результат нескольких лет профессиональной работы и простой открытости Васи, как человека. Вам до всего этого далеко, поэтому, как грица, завидуйте молча.

И пишу я всё это не для того, чтобы сказать вам, что вы завистливый хам, а возможно и подлый человек. Нет.

Пишу это для поддержки Василия, ибо дело он делает (а не пиздит, как ВАШЕ сообщество) совершенно благое и очень-очень нужное. И SD ему в этом помогает. За что им огромное спасибо. Но они это прекрасно знают и без меня :-)

p.s. кстати, Вась, мне кажется, или писать статьи на хабр как-то мало смысла? Ибо там в основном всегда такие вот срачи и переходы на личности в комментах происходят, а обсуждения по теме стремятся к нулю p.p.s. заранее предугадывая срач - всё сказанное выше относится исключительно к revo. Поэтому заслуг упомянутых людей и сообществ для ветки evo не принижаю совершенно.

Чикин Артур

всё сказанное выше относится исключительно к revo. Поэтому заслуг упомянутых людей и сообществ для ветки evo не принижаю совершенно.

В сообществе Evo как то по спокойней и по проще, там более адекватные люди сидят. Желчью друг на друга не капают.

Чикин Артур

Кстати что касается

Ты если сделал — молодец. А теперь грузи на сайт НАШего сообщества! Это же дело общее. А мы и дальше будем говорить, какой ты и твои SD самопиарившиеся мудаки.

У этого нашего сообщества есть владельцы, любой сайт кому нибудь да принадлежит. bezumkin.ru принадлежит Василию. modx-cms.ru - тоже не без хозяина.

Любое сообщество нужно модерировать. Следить и ухаживать. Здесь оно ухожено и можно найти полезную информацию. На крайний случай создать вопрос.

Но многие упираются рогами в стандартное мышление. Если сообщество то для него нужно создать отдельный домен и позиционировать как ресурс без хозяина. Но так не бывает.

modx-cms.ru - У него есть владелец и администратор modx.im - Тоже есть владелец и администратор modx.by - Точно так же есть владелец и администратор Так чем же bezumkin.ru так отличается от сайтов выше? А тем что у него в названии нету слова modx. Если бы сайт назывался как нибудь modx-bezumie.ru было бы меньше волнений.

Но простите? Я повторюсь, какая разница? Если Администраторы не смогли обеспечить пользователей необходимым а в последствии пользователи в некоторых вопросах предпочли Василия, так они сами и виноваты. Только льют желчь на всех подряд и пугают новичков.

Хотя... Нет не всех подряд, только на Василия.

Василий Наумкин

У меня специально нет слова MODX в названии сайта, так же как его нет и в других новых проектах.

Мало кого это волнует, но MODX LLC запрещает использование своей торговой марки в именах доменов.

Please Don’t…Using “modx” (in any form of capitalization) in a domain name is not permitted.

Они, конечно, закрывают на это глаза для разных сообществ, но мне в свое время сделали замечание за modx-test.com. С тех пор и не использую.

Василий Наумкин

Спасибо за добрые слова и поддержку!

На Хабр писать смысл пока еще есть - просто оповестить больше количество людей о новом проекте.

Илья Уткин

Это будет документация именно по дополнениям или по всем возможностям MODX? Например, я уже переводил официальную документацию о фильтрах ввода-вывода, синтаксисе тегов, существующих тегах ресурса и др., но это опять же на другом ресурсе. Есть возможность и желание помочь, но не знаю, что стоит писать, а что нет. Структурку бы хотя бы минимальную... И еще — указанные переводы размещались изначально на http://modx.im, стоит ли их переносить на новый ресурс, потому что как-то не хорошо получится дублировать контент.

Василий Наумкин

Это документация по всему, связанному с MODX. Пока есть раздел "Компоненты", но по структуре каталогов видно, что рядом с ним могут быть "Ядро", "Пошаговые инструкции" и еще много чего. Если есть что прислать - присылай, я распределю.

А по поводу дублирования - там еще половину информации нужно проверять и актуализировать. В итоге может выйти уже совсем не дубликат. Главное - начать что-то делать, а там разберемся =)

Чикин Артур

Вот согласен. MODX растет, а обучающие туториалы стареют но продолжают просто копироваться с сайта на сайт. Хотя уже давно потеряли актуальность...

Чикин Артур

Я думаю скорее дополнений, так как это самая ходовая информация и самая редкая на данный момент. А тем кому нужно ядро для написания чего либо все равно придется часто ходить на rtfm.modx.com

Что касается wiki.modx.im/revolution то он выглядит как заброшенное кладбище, без обид.

Илья Уткин

А есть возможность поменять адрес страницы вручную? Заменить http://docs.modx.pro/system/basics/filters-o-(modifiers-/-o)на http://docs.modx.pro/system/basics/input-and-output-filters-(output-modifiers)

Чикин Артур

Я так понимаю за адрес страницы отвечает ytranslate но есть возможность в ручную внести изменения в название)

Василий Наумкин

Тогда немного импорт поломается.

Можно переименовать страницу, сделать название "Фильтры вывода" и будет ок.

Василий Наумкин

Поправил.

Виталий Киреев

А как ссылаться с одной страницы на другую? И еще почему-то с моих пулреквестов постоянно тянется полотно коммитов еще предыдущего пулреквеста :\

Василий Наумкин

Ссылаться только указаием uri, больше не знаю как.

components/debugparser/plugin

Можно, в принципе, придумать свой формат, но он не будет особо отличаться от uri.

А история пусть тянется, не жалко!

Виталий Киреев

Еще в параметрах pdoMenu, которые показываются при перетягивании сниппета из дерева значение plPrefix - wf. В самом сниппете его упоминания не нашел, а в ядре пустое значение. Какое из них считать по умолчанию? По идее надо или добавить в сниппет как другие параметры совместимости с Wf или убрать из сниппет пропертис.

Василий Наумкин

По умолчанию - wf.

Это для совместимости с чанами Wayfinder. Кому не нужно - может указать пустой префикс. Сниппет без класса не работает, так что ничего менять не нужно. Он просто передает префикс в класс.

Чикин Артур

Сохрани изменения где нибудь Удали свой репозиторий Сделай новый форк Внеси изменения в новом форке Сделай пулреквест

Alex Vakhitov

Зачем столько лишнего делать? Проще сразу учится НОРМАЛЬНО работать в git. При первом же запросе к гуглу вылетела хорошая инструкция с хабра