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

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

    Зачем?

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

    Официальная документация на русском не ведётся. Не знаю, как сейчас, но год назад у них просто не сохранялась кириллица.

    Почему не сделать это на сайте n или z?

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

    Например, я пробовал писать про свои дополнения на официальном сайте, а потом они его переделали, и мой логин пароль больше не подходит. Просто зарегистрироваться нельзя — нужно получать их через письмо в поддержку. Конечно, повторно это делать нет желания.

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

    И что ты предлагаешь?

    Очень просто — нужно вести документацию в GitHub, в общеизвестном формате Markdown.

    Такая система гарантирует нам:
    • Сохранность всех текстов. Каждый человек может скопировать репозиторий и разместить у себя.
    • История изменений. Все правки как на ладони, видно кто и что написал.
    • Независимость. Вы можете писать о любой теме, касающейся MODX, на любом языке. И вам не нужно просить для этого доступ — достаточно иметь аккаунт на GitHub.


    Идея не новая, и подсмотрел я её у проекта daux.io. Это PHP скрипт, который генерирует сайт по готовым файлам markdown.
    Он очень простой, и позволяет запустить свой сайт с документацией, не обладая вообще никакими навыками, на любом хостинге. Однако, на мой взгляд, у него есть несколько недостатков (которые являются продолжением достоинств).

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

    Так что, для показа нашей документации я использовал любимую систему — MODX.

    Как работает?

    Это обычный сайт на MODX, построенный с использованием стандартных дополнений, но все его страницы импортируются из файлов.

    Это даёт:
    • Кэширование. Все документы будут загружаться из кэша, и не нужно каждый раз шерстить файлы на HDD.
    • Управление url документов — их можно перемещать, не теряя при этом переходы из поисковиков.
    • Возможность организовать поиск на сайте.
    • Удобная работа с языковыми версиями, их может быть сколько угодно.
    • Возможность, в будущем, включить на сайте авторизацию (HybridAuth) и комментарии (Tickets).


    В дереве сайта находятся долько документы.


    Я хочу сохранить возможность полного обновления дерева с предварительной очисткой таблицы, поэтому служебные страницы генерирую налету и не сохраняю в БД. Это новая придумка, посмотрим, как будет работать.

    Например, карта сайта выдаётся вот так:
    <?php
    if ($modx->event->name != 'OnHandleRequest' || $modx->context->get('key') == 'mgr') {return;}
    
    $alias = $modx->getOption('request_param_alias', null, 'alias');
    $request = strtolower($_REQUEST[$alias]);
    
    if ($request == 'sitemap.xml') {
    	$output = $modx->runSnippet('pdoSitemap', array('context' => 'web,en'));
    	exit($output);
    }
    


    А вот страницы поиска:
    elseif ($request == 'search') {
    	$doc = $modx->newObject('modResource');
    	$doc->fromArray(array(
    			'id' => 100000000,
    			'context_key' => $modx->context->key,
    			'pagetitle' => $modx->context->key == 'en' ? 'Search' : 'Поиск',
    			'template' => 3,
    			'content' => '
    				[[!pdoPage@Search?context=`'.$modx->context->key.'`]]
    				[[+page.nav]]
    			'
    		));
    	$modx->resource = $doc;
    	$response = $modx->getResponse();
    
    	$output = $modx->response->outputContent();
    	exit($output);
    }
    

    То есть, работа идёт через плагин на событие OnHandleRequest и зависит от контекста (языковой версии).

    Вёрстку я набросал на Bootstrap 3, чтобы было комфортно читать с телефонов и планшетов. Для работы используются:
    • pdoTools — вывод соседних документов, всех меню и хлебных крошек.
    • mSearch2 — морфологический поиск.
    • DateAgo — приятное форматировние дат
    • yTranslit — генерация url страниц через переводы Яндекс.
    • MinifyX — склейка и сжатие скриптов и стилей, для быстрой загрузки страниц.
    • Markdown — новый сниппет для вывода текстов в этом формате. Написал специально для этого проекта.


    Еще раз напоминаю, что эта документация никому не принадлежит. Я сделал свою версию сайта для её вывода, а вы можете склонировать репозиторий и запустить его на том же daux.io — структура директорий и файлов совместима.

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

    Ссылки

    Репозиторий документации на Gitub.
    Сайт с выводом этой документации.

    Планы на будущее: разработка простенького API для вывода текстов на других сайтах и (возможно) сокращалка url.

    Обновлено 15.01.2014


    В связи с недовольством доменным именем, перенесли документацию на docs.modx.pro.

    Надеюсь, больше возражений не будет.
    Поделиться публикацией

    Похожие публикации

    Комментарии 23
      0
      >>К тому же, сообщество MODX не может похвастаться сплоченностью, и основных разработчиков просто не собрать в одном месте, чтобы они что-то там написали.

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

        Что делать? Как вытаскивать информацию — из кэша гугла?

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

        Ах, да, про какое же именно сообщество речь?
        community.modx-cms.ru
        modx.im
        modx.ru
        modx.by
        или группы вконтакте?
          –1
          >>Что делать? Как вытаскивать информацию — из кэша гугла?

          Гитбах теоретически тоже может грохнуться. Документация должна идти в комплекте с компонентом + на каком-то общем сайте для удобства. Поэтому просто безвозвратно исчезнуть она не должна.

          >>Домен не имеет значения, уже сейчас любой может брать информацию из репозитория…

          Ага, давайте все вместе будем рекламировать Безумкина и СимплДрим :) Так дела не делаются.

          >>Ах, да, про какое же именно сообщество речь?

          Устроим выборы, делов-то :)
            +3
            Гитбах теоретически тоже может грохнуться.


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

            Ага, давайте все вместе будем рекламировать Безумкина и СимплДрим :) Так дела не делаются.


            Кстати, а почему нет? Если от их действий есть ощутимая польза для сообщества, то это нужно всячески приветствовать. Именно о таком явлении я говорил еще лет 7 назад. Вышло не так как хотелось, не так быстро, не так просто… Но здорово, что все же это получается в итоге. Проблема же на самом деле сейчас в другом. Такую же деятельность должна вести не одна студия, а целый ряд, а также индивидуальные разработчики. Тогда и СимплДрим не будет выглядеть белой вороной / выскочкой и другие участники будут получать существенную выгоду и для MODX будет реальная польза.
              +1
              давайте все вместе будем рекламировать Безумкина и СимплДрим :)

              Зачем? Они сами себя отлично рекламируют — своими делами. Не всем это нравится, конечно, но что поделать?

              Устроим выборы, делов-то :)

              Вот будет сюрприз, если победит bezumkin.ru =)
                –2
                >>Они сами себя отлично рекламируют — своими делами.

                В том числе самопиаром. У кого-то не хватает наглости и ресурсов на такой самопиар. Есть у нас сайт сообщества, но нет, мы будем грузить документацию Безумкину.
                  +1
                  Андрей, ты ведь и пальцем не пошевелишь, к чему эта зависть? Тем более, что сайт сообщества поддерживает мою идею.

                  Грузи документацию в сообщества, хоть во все сразу — что тебя останавливает?
                    0
                    А ты бы стал свои доки грузить мне, только четно? (не верю в твою честность)
                    >>к чему эта зависть?
                    Опять ты свои фантазии выдаешь за правду. Значит ошибался я, думая что ты начал меняться. Ответь мне лучше в своём блоге, чтобы не засорять Хабр или лучше вообще не отвечай.
                      +1
                      Я с удовольствием бы присоединился к такому проекту и был бы очень рад, если бы ты сделал это всё вместо меня.

                      Было бы круто просто поспать на праздниках, а потом прочитать твою новость, и прислать на GitHub описания своих дополнений.
                      Сделать форк, выгрузить на свой сайт и пропиарить идею.

                      Но ты ничего этого не сделал, да и сейчас явно не намерен помогать, так что вопрос ниочем. Очень прошу — просто не мешай, ладно?
          0
          Всё, что есть, разбросано по разным сообществам и блогам, которых несколько десятков, и любой начинающий пользователь бегает туда-сюда, задавая вопросы.

          Как бы это скептически не звучало, но по моему, вы решили пополнить этот список. Как документация для конкретно ваших дополнений — это хорошее решение, буду пользоваться. Но имхо, замахиваться на документацию к MODX довольно странно.

          По поводу сплоченности — это да, думаю, нужно стараться исправить конкретно эту проблему, а не крошить российское сообщество еще на более мелкие части.
            +1
            Почему странно? Susan Ottwell вчера перевела и прислала одну страничку — хороший знак. У меня в планах много всяких how-to, да и ядро MODX я могу описать процентов на 80.

            Либо мы принимаем мысль, что русской документации вообще не будет, или пытаемся её создать. Мой вариант для создания — лучший. Честно говоря, другого способа, который устроил бы всех возможных авторов, я не вижу.

            Есть другие идеи? Или только скепсис в наличии?
            +2
            Отлично! У меня параллельно именно такая же идея пришла в голову, я даже сделал репозитории в Github. Но до реализации пока не добрался. Стало быть это тренд уже. ;-)

            На мой взгляд это, наконец, действительно тот самый шанс придти к документации, о которой можно только мечтать нашему сообществу. Всячески призываю всех присоединиться к этому вопросу. :-)
              0
              Ребят, вы бы лучше пару статей написали о этой cms, да хотя бы с описанием маст хав плагинов и лучший практиках их использования. А то почти вся информация на хабре либо поверхностна, либо критикуется в комментариях как недостоверная.
                0
                Лучше написать документацию, чем писать документацию? Оригинально!

                Начать читать можно отсюда, основной must have компонент на сегодня.

                Остальные потихоньку наполняем.
                  –3
                  >>основной must have компонент на сегодня

                  Вот это самомнение :)) Это ты можешь своим школьникам рассказывать в блоге, но не тут. В прошлый раз я поддержал просто за вложенный труд, но наглеть не надо.
                    0
                    Ты отлично демонстрируешь, как у нас проходит всё общение разработчиков. Примерно так, да.

                    Но если по сути — назови другое дополнение, которое:
                    • Выводит меню
                    • Выводит ресурсы
                    • Выводит юзеров
                    • Хлебные крошки
                    • Соседние документы
                    • Карту сайта
                    • Произвольные поля документа
                    • Делает разбивку по страницам

                    Я уж молчу про остальные возможности, заложенные в классах, и собственном парсере.
                      –1
                      Ты правда думаешь, что не назову? Воспользуйся поиском тут modx.com/extras/
                        0
                        Не могу найти другого дополнения, которое столько же умеет, как pdoTools. Покажи. если не трудно.

                        Конечно, ты можешь предложить список из:
                        • Wayfilnder
                        • getResources (getProducts)
                        • getUserProfiles
                        • Breadcrumbs
                        • ???
                        • GoogleSitemap
                        • getResourceField + UltimateParent
                        • getPage

                        Кому-то интересно устанавливать 8 — 10 дополнений вместо одного? Тем более, вывода соседних документов я и вовсе не нашел.
                          0
                          ну, занудства ради, предыдущий элемент (по id) выводится как
                          [[getResources? &tpl=`prevId` &where=`{"id:<":[[*id]]}` &limit=`1` ]]
                            0
                            Соседние id легко могут быть в разных разделах или даже контекстах.

                            Так что, вывод должен идти по родителю и сортироваться по любому полю документа (menuindex, publishedon) — это совсем другая песня.

                            Вот исходный код сниппета, можно оценить.
                              0
                              Так что, вывод должен идти по родителю и сортироваться по любому полю документа (menuindex, publishedon) — это совсем другая песня

                              Ну да, это само собой подразумевается, я просто опустил &parents
                              Вот исходный код сниппета, можно оценить.

                              А вот то, что можно одним вызовом вывести и соседей, и родителя, это очень удобно, спасибо!
                                0
                                Собственно, на сайте документации ссылки на соседние документы так и выводятся.

                                Причем родитель подставляется если нет следующего или предыдущего фильтром вывода.
                0
                Объясняю ещё раз минусующим свою позицию:
                Нормальные люди, желающие добра сообществу MODX сделали бы так: разработали эту штуку и подарили бы, например, modx-cms.ru. Конечно, за такое дело можно там влепить баннер на вас (огромный).
                А не нормальные, которые хотят чтобы другие люди их рекламировали (давали на них ссылки) сделали всё под своим именем (адрес на гитбабе + адрес сайта документации).

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

                Самое читаемое