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.
Василий Наумкин
Круто, Просто круто)
Документацию может писать любой желающий - нужен только аккаунт на GitHub. Заходишь в нужный файл, жмешь edit и отправляешь мне.
Дальше я принимаю твои изменения (возможно, что-то редактирую) и выгружаю на сайт.
Если хочешь добавить прям раздел - тогда нужно будет сделать форк проекта. В общем, обычная работа с репозиторием - информации об этом полно.
Да) Просто статью прочитал немного не вьехал а потом главную Доков и уже стало понятно)
Я так понимаю документацию будем вести преимущественно на русском языке, для своих? Или на ломаном английском тоже?)
У меня всё готово для поддержки любых языков, но для начала надо бы с русским разобраться.
Переводить по готовому будет всяко проще. В любом случае, если кто пришлёт коммит на английском - добавлю его в соответствующую ветку.
Класс! Именно этого не хватало!
Очень хотел бы там увидеть раздел "Примеры". А еще лучше пошаговые инструкции... Можно и видео встроить. :)
А то часто приходится клиентам делать видео-касты показывая как в минишопе заполнять например товары.
Будет, со временем, можешь и сам добавить =)
С такими темпами скоро у нас будет свой форк MODX Revo с своими блэкджеком и шлюхами.
Репозиторий есть. Документация теперь своя.
Что еще нужно для полного счастья?)
Зачем форк?
Мы просто выстраиваем работу MODX в России, ибо среди авторов никто не говорит по-русски и за нас этого не сделает.
Классное начинание. Мне для открытой документации наравится readthedocs.org, ну а если хочется все хранить у себя то конечно sphinx-doc
Василий, это прекрасно! Идея просто чудо :)
У меня такой вопрос, если понадобится например в документации выводить картинки или иллюстрации как быть? Где будем их хранить?
Может их конвертировать в base64 images и хранить прям в git? Иди это будет не правильно?
P.S Прислал первый коммит.
Принял и добавил первый коммит.
Картинки лучше загружать пока ко мне, а там хочу сделать автоматическую выгрузку и обработку.
Возможно, это будет отдельной веткой в репозитории, а все ссылки на изображения будут автоматически заменяться - позже подумаем еще. Base64 хранить как-то не хочется.
А где можно посмотреть подробнее про синтаксис файлов md?
Как сделать табличку?
И я не могу понять как синхронизировать форки? Я получается делаю в своем и отправляю реквесты. Но не знаю что уже было добавлено а что нет.
На главной странице ссылка на документацию http://daringfireball.net/projects/markdown/syntax В markdown можно использовать html, а значит таблицы можно писать тегами.
По репозиториям ответ здесь. Можно не заморачиваться и удалять\ создавать форк каждый раз. Других способов я не знаю, но наверное, можно нагуглить.
Инструкция от самого гитхаба как синхронизировать форки
А на самом гитхабе это можно провернуть?
Сам всегда из консоли это делал, поэтому не знаю. Но скорей всего нет
Добавь в расширения какой нибудь wysiwyg Markdown редактор для того что бы онлайн посмотреть можно было перед отправкой коммита в документцию.
Например нашел: markitup
В какие расширения, о чем ты?
Markdown для того и нужен, чтобы работать без редакторов. Готовый файл показывает сам GitHub, например вот.
У тебя есть раздел Утилиты Туда бы добавить редактор в котором можно было бы сделать пред просмотр генерируемого документа. markitup поддерживает язык и имеет возможность пред просмотра.
В утилиты уже добавляю, только без markitup - там по другому всё работает.
Ну я только предложил как вариант)
Держи http://bezumkin.ru/utils/markdown
На гит хабе поддерживается табличка вот так:
У тебя вроде как нет(
У меня, вроде как, и не 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]]То все зависает и перестает отвечать, если вызывать так:
[[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]]То все нормально.
Нет, это не в markdown баг =)
Починил.
Теперь перестали отображаться ссылки. Не работает :
и
Всё поправил.
Я его видел! Видел! Новый редактор!!:))
Какая-то беда с картинками в статьях.
Пытаюсь вот тут открыть картинку любую: http://docs.simpledream.ru/components/hybridauth/providers/facebook
Вместо этого в pop окне совсем другое.
Поправил.
Нужно немного поправить верстку и заменить:
На
А будет раздел куда слать запросы по документации? А раздел пошаговых инструкций будет?
Мне вот очень интересно было бы узнать как правильно настроить права доступа для менеджера на 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 и не знаю его заслуг перед сообществом, поэтому возможно (и очень даже может быть) они есть. Но манера ведения диалога - это детский сад и закидывание какашками оппонента без всякой аргументации. Суть:
Это вообще даже не знаю как комментировать. "Ты если сделал - молодец. А теперь грузи на сайт НАШего сообщества! Это же дело общее. А мы и дальше будем говорить, какой ты и твои SD самопиарившиеся мудаки.". Он адекватен вообще? Я бы с таким человеком вообще в диалог не вступал - одна желчь, зависть и отсутствие аргументов. Зря только время тратить.
Andchir, я надеюсь вы это прочитаете - смиритесь с тем фактом, что сайт Василия - это новое сообщество. С диктатурой (целиком поддерживаю. Никакой демократии. Только аргументированная диктатура, но это, пожалуй, тема совершенно другого обсуждения), поэтому без присущих ВАШИМ сообществам пафоса и двуличия. С постоянной помощью новичкам, новыми и действительно нужными продуктами. И сформировавшимся ядром хорошей, доброй и лояльной аудитории, которое постоянно увеличивается и становится профессиональней (опять же - это огромная заслуга Василия). Это результат нескольких лет профессиональной работы и простой открытости Васи, как человека. Вам до всего этого далеко, поэтому, как грица, завидуйте молча.
И пишу я всё это не для того, чтобы сказать вам, что вы завистливый хам, а возможно и подлый человек. Нет.
Пишу это для поддержки Василия, ибо дело он делает (а не пиздит, как ВАШЕ сообщество) совершенно благое и очень-очень нужное. И SD ему в этом помогает. За что им огромное спасибо. Но они это прекрасно знают и без меня :-)
p.s. кстати, Вась, мне кажется, или писать статьи на хабр как-то мало смысла? Ибо там в основном всегда такие вот срачи и переходы на личности в комментах происходят, а обсуждения по теме стремятся к нулю p.p.s. заранее предугадывая срач - всё сказанное выше относится исключительно к revo. Поэтому заслуг упомянутых людей и сообществ для ветки evo не принижаю совершенно.
В сообществе Evo как то по спокойней и по проще, там более адекватные люди сидят. Желчью друг на друга не капают.
Кстати что касается
У этого нашего сообщества есть владельцы, любой сайт кому нибудь да принадлежит. bezumkin.ru принадлежит Василию. modx-cms.ru - тоже не без хозяина.
Любое сообщество нужно модерировать. Следить и ухаживать. Здесь оно ухожено и можно найти полезную информацию. На крайний случай создать вопрос.
Но многие упираются рогами в стандартное мышление. Если сообщество то для него нужно создать отдельный домен и позиционировать как ресурс без хозяина. Но так не бывает.
modx-cms.ru - У него есть владелец и администратор modx.im - Тоже есть владелец и администратор modx.by - Точно так же есть владелец и администратор Так чем же bezumkin.ru так отличается от сайтов выше? А тем что у него в названии нету слова modx. Если бы сайт назывался как нибудь modx-bezumie.ru было бы меньше волнений.
Но простите? Я повторюсь, какая разница? Если Администраторы не смогли обеспечить пользователей необходимым а в последствии пользователи в некоторых вопросах предпочли Василия, так они сами и виноваты. Только льют желчь на всех подряд и пугают новичков.
Хотя... Нет не всех подряд, только на Василия.
У меня специально нет слова MODX в названии сайта, так же как его нет и в других новых проектах.
Мало кого это волнует, но MODX LLC запрещает использование своей торговой марки в именах доменов.
Они, конечно, закрывают на это глаза для разных сообществ, но мне в свое время сделали замечание за 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, больше не знаю как.
Можно, в принципе, придумать свой формат, но он не будет особо отличаться от uri.
А история пусть тянется, не жалко!
Еще в параметрах pdoMenu, которые показываются при перетягивании сниппета из дерева значение plPrefix - wf. В самом сниппете его упоминания не нашел, а в ядре пустое значение. Какое из них считать по умолчанию? По идее надо или добавить в сниппет как другие параметры совместимости с Wf или убрать из сниппет пропертис.
По умолчанию - wf.
Это для совместимости с чанами Wayfinder. Кому не нужно - может указать пустой префикс. Сниппет без класса не работает, так что ничего менять не нужно. Он просто передает префикс в класс.
Сохрани изменения где нибудь Удали свой репозиторий Сделай новый форк Внеси изменения в новом форке Сделай пулреквест
Зачем столько лишнего делать? Проще сразу учится НОРМАЛЬНО работать в git. При первом же запросе к гуглу вылетела хорошая инструкция с хабра