Сейчас есть много разных источников: сообщества, официальный сайт, вики и у всех у них есть большие недостатки:
- Нужно получить логин и пароль от хозяев сайта
- Неудобное редактирование
- Далеко не всегда есть контроль версий
- Сайт может закрыться в любой момент, и весь твой вклад останется только в кэше гугла
Просить новый, как вы понимаете, желания нет. А вот организовать качественную документацию, с которой будет удобно работать всем желающим — есть.
И вот мне на глаза попался проект daux.io, который генерирует сайт динамически, по статичным страницам. Сами страницы должны быть формата Markdown, и могут храниться где угодно, например в GitHub!
Таким образом? выходит очень удобная работа с документацией, редактор не нужен, логин и пароль от GitHub у большинства разработчиков уже есть.
Более того, эта документация никому не принадлежит! Она не пропадёт и не исчезнет — каждый может её скопировать и развернуть у себя на сайте. Она хранит все правки, каждую из них можно обсудить. Если вам нечего написать — вы можете исправлять опечатки.
В общем, сплошные плюсы. Но и минусы у реализации в виде daux.io тоже есть:
- Неудобное управление шаблоном. Фактически, он вшит прямо в index.php
- Отсутствие мультиязычности в оформлении страниц. Сами страницы можно вести на разных языках, а вот отображать даты в разных форматах — никак.
- Нет кэширования, неизвестно каких объемов документацию он потянет. А если там 5000 документов, это при каждом запросе нужно сканировать всё дерево, чтобы сгенерировать меню?
- Нет встроенного поиска. Конечно, Google поможет, но когда еще он проиндексирует сайт, и насколько хорошо?
- Нет перенаправления с одного адреса на другой, при переносе документа. А вдруг кто-то ошибся в имени файла?
- Довольно много ошибок в коде: 80 закрытых и еще 20 открытых. И это на проект, с двумя основными php файлами.
Вот что у меня получилось — docs.simpledream.ru.
Пример заполненной страницы — вот.
Шаблон работает на третьем Bootstrap, проверил всё на мобильниках и планшетах — проблем нет, читать приятно.
В ближайшие дни я постараюсь плотно заняться пополнением документации, и очень прошу вас помочь в этом начинании. Вам нужно просто сделать pull request, и постараться следовать простеньким правилам, описанным на главной странице.
Следующий этап — это разработка api для встраивания текстов с сайта на другие ресурсы. Чтобы вы писали в одном месте, а пользоваться можно было где угодно. Может, даже какие-то короткие ссылки приделаю, чтобы было удобно посылать всех читать =)
Надеюсь, идея приживётся и у нас наконец-то появится хорошая документация для MODX Revolution! Очень надеюсь на вашу помощь в наполнении. Как говорится, плиз retweet.
← Следующая заметка
Опровержение
Опровержение
Предыдущая заметка →
С наступающим, 2014 годом
С наступающим, 2014 годом
Дальше я принимаю твои изменения (возможно, что-то редактирую) и выгружаю на сайт.
Если хочешь добавить прям раздел — тогда нужно будет сделать форк проекта. В общем, обычная работа с репозиторием — информации об этом полно.
Я так понимаю документацию будем вести преимущественно на русском языке, для своих? Или на ломаном английском тоже?)
Переводить по готовому будет всяко проще. В любом случае, если кто пришлёт коммит на английском — добавлю его в соответствующую ветку.
Очень хотел бы там увидеть раздел «Примеры». А еще лучше пошаговые инструкции… Можно и видео встроить. :)
А то часто приходится клиентам делать видео-касты показывая как в минишопе заполнять например товары.
Репозиторий есть.
Документация теперь своя.
Что еще нужно для полного счастья?)
Мы просто выстраиваем работу MODX в России, ибо среди авторов никто не говорит по-русски и за нас этого не сделает.
Может их конвертировать в base64 images и хранить прям в git? Иди это будет не правильно?
P.S Прислал первый коммит.
Картинки лучше загружать пока ко мне, а там хочу сделать автоматическую выгрузку и обработку.
Возможно, это будет отдельной веткой в репозитории, а все ссылки на изображения будут автоматически заменяться — позже подумаем еще. Base64 хранить как-то не хочется.
Как сделать табличку?
И я не могу понять как синхронизировать форки? Я получается делаю в своем и отправляю реквесты. Но не знаю что уже было добавлено а что нет.
В markdown можно использовать html, а значит таблицы можно писать тегами.
По репозиториям ответ здесь. Можно не заморачиваться и удалять\ создавать форк каждый раз. Других способов я не знаю, но наверное, можно нагуглить.
Например нашел:
markitup
Markdown для того и нужен, чтобы работать без редакторов. Готовый файл показывает сам GitHub, например вот.
У тебя вроде как нет(
А там есть кое-какие изменения.
Попробую прикрутить попозже.
Хорошо что есть такие люди в сообществе MODx!!!
К тому же, markdown очень легко конвертируется в HTML — можно и его попробовать загнать в Dash.
Если использовать конструкцию вида:
``` [[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` ]] ```То все нормально.Починил.
Не работает:
и
Пытаюсь вот тут открыть картинку любую: 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%; }Мне вот очень интересно было бы узнать как правильно настроить права доступа для менеджера на miniShop2. Я сам уже делал это несколько раз, но всегда какие-то грабли были.
Вот ты разберись с разрешениями (там их всего 2: mscategory_save и msproduct_save), напиши заметку, да пришли в репозиторий, чтобы все могли прочитать.
Вот в следующий раз когда будешь настраивать права доступа, сделай быстренько набросок и кинь в репозиторий. Там для него уж место найдется.
Или когда будет свободное время возьми и перенеси какую нибудь документацию о других компонентах. Тут как говорится пока сам не сделаешь ничего не будет.
Сделал по алфавиту.
Не кто 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 не принижаю совершенно.
У этого нашего сообщества есть владельцы, любой сайт кому нибудь да принадлежит. bezumkin.ru принадлежит Василию. modx-cms.ru — тоже не без хозяина.
Любое сообщество нужно модерировать. Следить и ухаживать. Здесь оно ухожено и можно найти полезную информацию. На крайний случай создать вопрос.
Но многие упираются рогами в стандартное мышление. Если сообщество то для него нужно создать отдельный домен и позиционировать как ресурс без хозяина. Но так не бывает.
modx-cms.ru — У него есть владелец и администратор
modx.im — Тоже есть владелец и администратор
modx.by — Точно так же есть владелец и администратор
Так чем же bezumkin.ru так отличается от сайтов выше? А тем что у него в названии нету слова modx.
Если бы сайт назывался как нибудь modx-bezumie.ru было бы меньше волнений.
Но простите? Я повторюсь, какая разница? Если Администраторы не смогли обеспечить пользователей необходимым а в последствии пользователи в некоторых вопросах предпочли Василия, так они сами и виноваты. Только льют желчь на всех подряд и пугают новичков.
Хотя… Нет не всех подряд, только на Василия.
Мало кого это волнует, но MODX LLC запрещает использование своей торговой марки в именах доменов.
Они, конечно, закрывают на это глаза для разных сообществ, но мне в свое время сделали замечание за modx-test.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)
Можно переименовать страницу, сделать название «Фильтры вывода» и будет ок.
Можно, в принципе, придумать свой формат, но он не будет особо отличаться от uri.
А история пусть тянется, не жалко!
Это для совместимости с чанами Wayfinder. Кому не нужно — может указать пустой префикс.
Сниппет без класса не работает, так что ничего менять не нужно. Он просто передает префикс в класс.
Удали свой репозиторий
Сделай новый форк
Внеси изменения в новом форке
Сделай пулреквест