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.
0
👍
👎
❤️
🔥
😮
😢
😀
😡
4 983
06.01.2014, 16:13:54
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
На гит хабе поддерживается табличка вот так:
У тебя вроде как нет(
Василий Наумкин
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]]
То все зависает и перестает отвечать, если вызывать так:
[[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
]]
То все нормально.
Василий Наумкин
08.01.2014, 09:25:53
Нет, это не в markdown баг =)
Починил.
Чикин Артур
08.01.2014, 16:47:05
Теперь перестали отображаться ссылки. Не работает :
и
Василий Наумкин
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
Нужно немного поправить верстку и заменить:
На
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 и не знаю его заслуг перед сообществом, поэтому возможно (и очень даже может быть) они есть. Но манера ведения диалога - это детский сад и закидывание какашками оппонента без всякой аргументации. Суть:
Это вообще даже не знаю как комментировать. "Ты если сделал - молодец. А теперь грузи на сайт НАШего сообщества! Это же дело общее. А мы и дальше будем говорить, какой ты и твои SD самопиарившиеся мудаки.". Он адекватен вообще? Я бы с таким человеком вообще в диалог не вступал - одна желчь, зависть и отсутствие аргументов. Зря только время тратить.
Andchir, я надеюсь вы это прочитаете - смиритесь с тем фактом, что сайт Василия - это новое сообщество. С диктатурой (целиком поддерживаю. Никакой демократии. Только аргументированная диктатура, но это, пожалуй, тема совершенно другого обсуждения), поэтому без присущих ВАШИМ сообществам пафоса и двуличия. С постоянной помощью новичкам, новыми и действительно нужными продуктами. И сформировавшимся ядром хорошей, доброй и лояльной аудитории, которое постоянно увеличивается и становится профессиональней (опять же - это огромная заслуга Василия). Это результат нескольких лет профессиональной работы и простой открытости Васи, как человека. Вам до всего этого далеко, поэтому, как грица, завидуйте молча.
И пишу я всё это не для того, чтобы сказать вам, что вы завистливый хам, а возможно и подлый человек. Нет.
Пишу это для поддержки Василия, ибо дело он делает (а не пиздит, как ВАШЕ сообщество) совершенно благое и очень-очень нужное. И SD ему в этом помогает. За что им огромное спасибо. Но они это прекрасно знают и без меня :-)
p.s. кстати, Вась, мне кажется, или писать статьи на хабр как-то мало смысла? Ибо там в основном всегда такие вот срачи и переходы на личности в комментах происходят, а обсуждения по теме стремятся к нулю p.p.s. заранее предугадывая срач - всё сказанное выше относится исключительно к revo. Поэтому заслуг упомянутых людей и сообществ для ветки evo не принижаю совершенно.
Чикин Артур
13.01.2014, 07:28:20
В сообществе Evo как то по спокойней и по проще, там более адекватные люди сидят. Желчью друг на друга не капают.
Чикин Артур
13.01.2014, 09:13:06
Кстати что касается
У этого нашего сообщества есть владельцы, любой сайт кому нибудь да принадлежит. 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 запрещает использование своей торговой марки в именах доменов.
Они, конечно, закрывают на это глаза для разных сообществ, но мне в свое время сделали замечание за 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, больше не знаю как.
Можно, в принципе, придумать свой формат, но он не будет особо отличаться от 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. При первом же запросе к гуглу вылетела хорошая инструкция с хабра
bezumkin.ru
Личный сайт Василия Наумкина
Прямой эфир
Василий Наумкин
03.12.2024, 13:13:34
Генерация - это создание статичный файлов, для их работы потом pm2 не нужен, только правильная настр...
Василий Наумкин
01.07.2024, 11:56:41
Да, верно, именно так.
А в контроллере, скорее всего, ловить данные методом post.
Василий Наумкин
26.06.2024, 09:38:15
О, точно, вылезает если не залогинен.
Спасибо, исправил!
Василий Наумкин
09.04.2024, 04:45:01
> Ошибка 500
Это не похоже на ошибку Nginx, это скорее всего ошибка PHP - надо смотреть его логи.
...
russel gal
09.03.2024, 20:17:18
> А этот стоило написать хотя бы затем, чтобы получить комментарий от юзера, который ничего не писал...
Александр Наумов
27.01.2024, 03:06:18
Василий, спасибо!
Извини, тупанул.