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 комментарий

Чикин Артур

06.01.2014, 20:20:20

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

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

06.01.2014, 20:27:04

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

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

Чикин Артур

06.01.2014, 20:32:58

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

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

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

06.01.2014, 20:35:41

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

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

Scorp Satex

06.01.2014, 20:30:22

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

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

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

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

06.01.2014, 20:31:17

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

Чикин Артур

06.01.2014, 20:44:22

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

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

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

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

06.01.2014, 20:45:40

Зачем форк?

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

Alex Vakhitov

07.01.2014, 00:19:22

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

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

07.01.2014, 08:06:33

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

Чикин Артур

07.01.2014, 17:09:54

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

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

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

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

07.01.2014, 17:33:11

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

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

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

Чикин Артур

07.01.2014, 19:42:21

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

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

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

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

07.01.2014, 21:40:06

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

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

Alex Vakhitov

07.01.2014, 22:49:06

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

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

11.01.2014, 13:48:16

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

Alex Vakhitov

11.01.2014, 14:04:08

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

Чикин Артур

07.01.2014, 21:24:50

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

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

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

07.01.2014, 21:50:43

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

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

Чикин Артур

07.01.2014, 22:08:30

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

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

07.01.2014, 22:10:50

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

Чикин Артур

07.01.2014, 22:37:44

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

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

07.01.2014, 23:03:47

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

Чикин Артур

07.01.2014, 23:09:15

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


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

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

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

07.01.2014, 23:11:42

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

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

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

07.01.2014, 23:16:10

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

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

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

07.01.2014, 23:28:16

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

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

07.01.2014, 18:02:54

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

Денис А.

07.01.2014, 21:23:56

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

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

07.01.2014, 21:50:57

На здоровье!

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

07.01.2014, 22:23:06

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

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

07.01.2014, 22:53:47

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

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

Чикин Артур

08.01.2014, 05:18:54

Баг в 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]]

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

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

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

08.01.2014, 09:25:53

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

Починил.

Чикин Артур

08.01.2014, 16:47:05

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

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

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

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

08.01.2014, 22:01:59

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

Чикин Артур

08.01.2014, 19:22:24

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

Scorp Satex

08.01.2014, 23:43:55

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

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

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

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

09.01.2014, 00:40:13

Поправил.

Чикин Артур

09.01.2014, 01:48:04

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


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

10.01.2014, 20:49:11

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

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

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

10.01.2014, 23:27:53

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

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

Чикин Артур

11.01.2014, 05:15:27

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

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

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

Чикин Артур

11.01.2014, 05:17:15

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

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

11.01.2014, 13:59:24

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

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

11.01.2014, 13:45:38

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

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

11.01.2014, 14:07:20

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

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

Чикин Артур

13.01.2014, 01:37:48

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

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

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

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

13.01.2014, 01:45:11

Так и живём.

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

Чикин Артур

13.01.2014, 02:21:18

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

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

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

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

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

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

13.01.2014, 02:27:48

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

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

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

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

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

Чикин Артур

13.01.2014, 02:33:56

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

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

13.01.2014, 03:55:54

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

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

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

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

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

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

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

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

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

Чикин Артур

13.01.2014, 07:28:20

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

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

Чикин Артур

13.01.2014, 09:13:06

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

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

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

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

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

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

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

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

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

13.01.2014, 10:07:18

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

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

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

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

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

13.01.2014, 10:01:41

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

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

Илья Уткин

13.01.2014, 02:21:17

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

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

13.01.2014, 02:25:08

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

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

Чикин Артур

13.01.2014, 02:29:03

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

Чикин Артур

13.01.2014, 02:26:42

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

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

Илья Уткин

15.01.2014, 18:47:05

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

Чикин Артур

15.01.2014, 18:49:35

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

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

15.01.2014, 18:53:26

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

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

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

15.01.2014, 19:15:05

Поправил.

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

16.01.2014, 22:44:42

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

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

16.01.2014, 22:46:52

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

components/debugparser/plugin

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

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

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

16.01.2014, 22:51:26

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

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

16.01.2014, 23:01:40

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

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

Чикин Артур

16.01.2014, 22:49:26

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

Alex Vakhitov

17.01.2014, 13:03:25

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