[Markdown] Упрощаем жизнь менеджерам

Давняя и распространённая проблема — сделал сайт, и нужно его как-то сдать заказчику.

Заказчик, конечно, «непрограммист», этих ваших тегов не знает и хочет чтобы было просто. Есть масса редакторов, которые, вроде как, должны упрошать жизнь, да только работают они далеко не идеально. Например, вставьте таблицу из Office в TinyMCE — будет круто.

Моё мнение таково, что редакторы нужно отключать, использовать можно только Ace или MarkItUp, а заказчик должен учить HTML. Ну честное слово, для управления автомобилем он же учит правила и сдаёет на права? А ведь некоторые сайты дороже иных автомобилей — тут тоже думать нужно.

Но вот после разработки сайта документации стало ясно, что можно очень упростить жизнь при помощи Markdown.

Синтаксис там простейший, можно легко делать списки, таблички, ссылочки и пр. Всё это запоминается за день, нужно только немного практики.

Чего не хватает? Верно — сниппета, который будет этот Markdown выводить на сайте. Ну я его и написал!

Параметры

Итак, сниппет включает в себя 3 парсера, которые работают по разным правилам:
  • Markdown — стандартный, классический вариант
  • MarkdownExtra — расширенный вариант, с поддержкой таблиц. Он включен по умолчанию.
  • Parsedown — быстрый парсер, поддерживающий Github flavored markdown. Например, там есть автосоздание ссылок.
Это был параметр &mode=`MarkdownExtra`.

Есть еще параметры &escapeTags и &stripTags. Первый экранирует все теги MODX, не давая им выполняться (он включен по умолчанию).

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

Таким образом, среднестатистический менеджер может пользоваться markdown + html, а вот теги MODX вызывать не сможет — мало ли, чего наколдует?

Особенности

В markdown встречается много ковычек `, которые парсер MODX воспринимает, как родные, и пытается обработать или вырезать.
Конечно, хорошего из этого ничего не выходит, поэтому обычная передача тегов в сниппет отключена!

Сниппет должен сам выбрать поле документа, и спокойно обработать — без парсера MODX. Так что, у сниппета есть еще 2 параметра:
  • &id — Id ресурса. Если не указан, сниппет пытается использовать текущий.
  • &field — Поле для работы, по умолчанию — content.
В шаблоне вывода страницы можно вызывать просто:
[[Markdown]]
А вот в чанке pdoResources — можно вот так:
[[Markdown?id=`[[+id]]`&field=`[[+introtext]]`]]

Заключение

Новый сниппет уже можно качать из нашего репозитория.

Протестировать работу можно у меня на сайте, в утилитах.

Исходный код лежит в репозитории на GitHub.

Еще много примеров готовых страниц находится в документации.

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

Следующая заметка
[pdoTools] 1.9.0 - улучшения парсера и фильтрации по ТВ
Предыдущая заметка
[Tickets] Версия 1.2.4-rc Множество исправлений


Комментарии ()

  1. Чикин Артур 08 января 2014, 18:48 # 0
    Да, я его сегодня ждал:)

    Еще бы в админ панель подобное, вместо tinymce.
    1. Чикин Артур 08 января 2014, 19:08 # 0
      Может пускай сниппет сам для себя при установке папку создаст? Как и все остальные твои сниппеты.
      1. Чикин Артур 08 января 2014, 19:46 # 0
        Все разобрался как работает.
      2. Chero 08 января 2014, 19:32 # 0
        А нет редактора, который оставляет HTML теги в их основном виде? Давно ищу, но так и не нашел.
        Т.е. чтобы вид был как в TinyMCE->показать HTML и при этом был редактор с возможностю выбора какие теги/элементы вставить?

        Раньше тоже вручную теги прописывал, а потом надоело — открыть/закрыть))
        TinyMCE удобен тем, что позволяет скопировать текст с предврительными тегами, но вот каждый раз переключаться на HTML и чистить, да еще избавляться от дурацких стилей уже неудобно.

        Ну и плюс, он все же учит пользователя HTML синтаксису, если пользователь совсем без знаний.
        1. Василий Наумкин 08 января 2014, 20:45 # 0
          MarkitUp в официальном репозитории — только он у меня сейчас не открывается.
          1. Chero 08 января 2014, 23:10 # 0
            Спасибо, то что искал! Эх, жаль не поддерживается и подсветки синтаксиса нет((

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

        2. Viktor Minator 08 января 2014, 21:52 # 0
          Думаю следующим логичным шагом будет дополнение для публикации через stackedit.io/, что существенно улучшит жизнь тех же менеджеров ;). Сам пользуюсь и другим советую данный сервис.
          1. Ivan Kuzmuk 09 января 2014, 03:42 # 0
            Спасибо за линк!
          2. Дмитрий Ломакин 09 января 2014, 08:36 # 0
            В стандартном репозитарии есть «Markdown Parser»
            Изумительно и стабильно работает.

            из практического опыта:
            MODX и HTML теги нужно оставлять, без них никак при ситуации «не просто текст»

            может предыдущий опыт накладывает отпечаток на мое мышление (1С), но меня в ужас приводит мысль пускать в админку сайта не админа, поэтому разделяю
            контекст/дизайн/программирование
            вроде получается
            1. Василий Наумкин 09 января 2014, 08:50 # 0
              Возможно, изумительно, но:
              1. Версия плагина от 2011 года, внутри парсер от 2009 года.
              2. Это плагин, а не сниппет — его нельзя использовать при выводе списка документов.
              3. Юзер должен писать код в тегах
              <markdown></markdown>
              Моя задача, сделать хорошо не программистам, а менеджерам, коих в админке MODX очень много. Тем более, что MODX позволяет очень гибко настроить права, и остаются только проблемы «ой, я вставил табличку из word и всё поехало!».
              1. Дмитрий Ломакин 09 января 2014, 14:48 # 0
                1. не особо понял смысл. ну старый, ну и что? работает безупречно, что еще надо то?
                2. «его нельзя использовать при выводе списка документов.» — опять не понял
                3. не обязательно ). у меня в файлах все лежит, теги модх приписывает, пользователи даже не догадываются.

                PS мое ИМХО менеджеров в админке не должно быть вообще.
                PPS я то не против нового сниппета, я за более глубокие знания возможных вариантов.
                1. Василий Наумкин 09 января 2014, 19:36 # 0
                  Это нужно у автора спросить, зачем он продолжает разрабатывать свою библиотеку, если она работает безупречно с 2009 года.

                  Последняя версия, тем временем, от 29.11.2013.
                  1. Дмитрий Ломакин 10 января 2014, 09:28 # 0
                    отвечать на понты не буду.
                    Поучиться у тебя в программировании есть чему. Мне этого достаточно
                    1. Василий Наумкин 10 января 2014, 11:06 # 0
                      Да причем здесь понты?

                      Речь о том, что парсер развивается с 2007 по 2013 год, а ты утверждаешь, что версия от 2009 «работает безупречно». Посмотри историю коммитов с 2009 года — там все уже переписано по 10 раз.

                      Например, вот код:
                      ```
                      	Код
                      ```
                      
                      Старая версия выдаст его вот так:
                      <p><code>Код</code></p>
                      А новая версия вот так:
                      <pre><code>    Код
                      </code></pre>
                      Как видишь, старая версия просто скушала табуляцию и вместо pre добавила p. А в официальной документации, написано, как именно должен обрабатываться код. Как в новой версии.

                      Более того, старая версия сжирает еще и переносы строк, и мой исходный код выводится в одну линию. То есть, на сайте документации её просто нельзя использовать.

                      А вот этот код старая версия вообще не вывела — показала 6 ковычек, с пустотой внутри:
                      ```
                      [[!pdoPage?
                      	&tpl=`@INLINE <p>[[+idx]] <a href="/[[+uri]]">[[+pagetitle]]</a></p>`
                      ]]
                      [[!+page.nav]]
                      ```
                      
                      Наверное потому, что парсер MODX обработал эти теги раньше — ведь плагин срабатывает в самом конце подготовки страницы.

                      А ты говоришь, «безупречно», «понты».
                      1. Дмитрий Ломакин 10 января 2014, 13:16 # 0
                        1. Спасибо. Доходчиво.
                        2. Про понты — наверное я не так понял твои слова. У тебя достаточно своеобразный стиль общения. Высокомерный. Будем считать что это мое восприятие такое неадекватное, и мне над ним надо поработать ). Извини если обидел, не хотел. В общем проехали.
                        3. Мы говорим о mardown для менеджеров. У меня востребовано:
                        размер заголовка (#, ##, ###...),
                        жирно, курсив
                        вставить рисунок
                        чанки и вкрапления HTML работают нормально. Например:
                        <img src="ext/brand/[[+brand]]/logo.png" alt="Логотип [[+brand]]" align="left" >
                        мне этого было достаточно и оно работало для меня безупречно.
                        То что появился еще один инструмент, тоже замечательно.
                        Я здесь писал для информации об альтернативе. Мыло ли. Вдруг у кого-то где-то твой код не заработает. както так.
            2. Дмитрий Ломакин 09 января 2014, 08:40 # 0
              К слову, под Windows долго найти не мог нормальный редактор
              нашел, бесплатный, рекомендую.
              MarkdownPad 2
              markdownpad.com

              может работать как portable, у меня в dropbox лежит
              Недостаток только один — долговато запускается
              1. Виталий Киреев 09 января 2014, 19:32 # 0
                заказчик должен учить HTML
                Эх, если бы… :) Боюсь «менеджеры» не захотят учить новую разметку, так же как и не хотят учить HTML. Им надо, чтобы было все как в Ворде, т.к. они только его знают и ничего нового знать обычно не хотят.
                1. Василий Наумкин 09 января 2014, 19:33 # 0
                  Да тут проще чем в ворде.

                  В любом случае — показать и предложить стоит.
                  1. Chero 09 января 2014, 23:35 # 0
                    Не спора ради, просто, хотел объяснить логику менеджеров, как я ее услышал )) Тут дело не только и не столько в тегах.

                    Плюс TinyMCE (он же Word) перед любыми решениями с тегами в том, что в них как отображается в админке, так выведется и во фронтенде. Даже если залезешь в html, то теги за тебя поправляются.
                    А в любых решениях с тегами — в админке одно, а на сайте — другое и поди разбери, в чем проблема — толи теги криво написал, толи сайт «глючит» и надо админа звать.

                    Вопрос, как мне кажется в другой плоскости немного. В том, кто занимается сайтом? Если тот же менеджер, что и продажами занимается, то тут только TinyMCE спасет. Если отдельный менеджер контента, то пусть теги учит и не выпендривается.
                  2. Дмитрий Ломакин 10 января 2014, 13:20 # 0
                    Самый крутой недостаток использования HTML для вывода контента — парные теги. Не поставил закрывающий, и глядишь на странице черте что получилось.
                    Markdown гораздо удобнее для контента.
                  3. Перетягин Илья 17 января 2014, 17:09 # 0
                    Самая приятная новость за этот год ).
                    Действительно решает много проблем с менеджерами, да и свой сайт наполнять становиться проще, быстрее. На самом деле просто не могу подобрать слова насколько мне это решение понравилось, но как обычно бывает, возникают вопросы….

                    Есть ли возможность менять хтмл код, который Markdown потом поставит?
                    Например, я хочу создать простой список, открываю модх и пишу:

                    * красный
                    * черный
                    * белый

                    Собственно на выходе получаю:
                    <ul>
                    	<li>красный</li> 
                    	<li>черный</li> 
                    	<li>белый</li> 
                    </ul>
                    

                    А мне надо, что бы список выглядел вот так:
                    <ul>
                    	<li><i class="fa"></i>красный</li> 
                    	<li><i class="fa"></i>черный</li> 
                    	<li><i class="fa"></i>белый</li> 
                    </ul>
                    

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

                    1. Василий Наумкин 17 января 2014, 17:12 # 0
                      А ты можешь спокойно использовать html и делать так:
                      * <i class="fa"></i>красный
                      * <i class="fa"></i>черный
                      * <i class="fa"></i>белый
                      
                      Ну и пошарься по документации MarkdownExtra — там вроде можно тегам классы указывать.
                      1. Перетягин Илья 17 января 2014, 17:17 # 0
                        Данное решение чем и понравилось, что надо меньше писать, добавление своего хтмл кода, когда видно, что можно сделать по человечески, как то… Но, побегаю еще по документации, посмотрим что будет. Спасибо большое за быстрые ответы!

                        п.с. в письме, оповещении, что есть комментарий к теме, в его заголовке присутствует немного ереси — Ответ на ваш комментарий к тикету "[Markdown] Упрощаем жизнь менеджерам"
                        1. Василий Наумкин 17 января 2014, 17:18 # 0
                          Ничего не поделать — скобочки у меня везде экранируются.
                    2. Антон Соловьёв 25 января 2014, 21:50 # 0
                      Для полноты менеджерского счастья тока визуального редактора в админке не хватает под Markdown
                      Если ещё и под bbcode будет — тогда вообще полный арсенал
                      1. Антон Соловьёв 25 января 2014, 22:01 # 0
                        Почитал чуток — походу TinyMCE можно и на Markdown и на bbcode настроить, я это правильно понял?
                        1. Василий Наумкин 25 января 2014, 22:03 # 0
                          Зачем?!

                          Звездочки, решетки и черточки без редактора нельзя писать?
                          1. Антон Соловьёв 26 января 2014, 10:18 # 0
                            Ну так удобней написать слова через энтер, потом выделить мыхой и жмякнуть на кнопку «список» и ап — не нужно у каждого слова писать 1., 2. т.д.
                            Или выделить абзац и жмякнуть мыхой «это цитата» — и перед каждой строчкой появится ">", не надо на каждую персонально ставить. Да и даже чисто hr поставить — аж три раза жмякнуть на * или один раз мыхой в соответствующую кнопку? Пользователи второе любят, они балованные и капризные. Вот даже здесь можно не писать b, а жмякнуть кнопк.
                            А если мы предлагаем им писать чистый код, пусть и Markdown, но чуть ли не руками аж три звездочки жмякнуть, которые на сайте превратятся в hr, то они должны иметь возможность посмотреть на то, что получается и сравнить это с написанным кодом. А то ж память подводит, вроде звездочки нужно поставить, но точно мол не помню, сэкспериментирую. Т.е. нужен тогда уж предпросмотр, которым можно воспользоваться перед тем, как жмякать на «Сохранить». TinyMCE — визуальный редактор, показывает, как код будет выглядеть на сайте. И там есть Toggle Editor, позволяющая смотреть чистый код. Если б не это, пользователи просили бы предпросмотр «как в вордпресе». Т.е. в принципе всё описанное выше в TinyMCE (и TypoMCE) есть, сниппет под Markdown вы представили, сниппет для bbcode можно и самому сварганить или нагуглить.
                            Ну т.е. красота, я здесь просто отвечаю на вопрос «зачем»
                            ЗЫ Эт все для манагероф, меня Ace устраивает. Вот если б он ещё мог закрывающий тег выделять. Чтобы поставил курсор на открывающим
                            <div>
                            , и он подсветился б и
                            </div>
                            1. Василий Наумкин 26 января 2014, 10:23 # 0
                              Эт все понятно, но Markdown настолько прост, что дальше уже некуда.

                              Если уж очень хочется — под него легко можно настроить MarkItUp, только предпросмотра нет. Но и это не проблема — сохранил, обновил страницу, посмотрел.

                              P.S. Пиши хотелку автору, иначе как он про неё узнает?
                              1. Антон Соловьёв 26 января 2014, 10:32 # 0
                                Вот именно- сохранил. Если страница опубликована, её не создают, а правят, то после сохранения правки будут доступны посетителю сайта. А манагер желает и тренироваться на боевой странице и чтоб его эксперемент посетитель не увидел. Кнопк Toggle Editor и отключаемая ею визуализация кода для этого лучше.
                                В MarkItUp для EVO, кстати работает подсветка кода EditArea. Удобно там получалось. С код Мирроу не ставил.
                                1. Василий Наумкин 26 января 2014, 10:35 # 0
                                  Если страница уже написана — там немного нужно исправить. Тем более, её уже написали, понятно, что и как.
                                  Если же менеджер пишет в первый раз, не нужно тренироваться на опубликованных страницах.

                                  В общем, делай как знаешь, но с TinyMCE я бы не стал связываться.
                                  1. Антон Соловьёв 26 января 2014, 10:47 # 0
                                    Что, в TinyMCE всё так жестко, лучше не соваться в него?
                                    1. Александр Котлов 26 января 2014, 13:55 # 0
                                      Если пользуешься им не сам — то потом замучаешься верстку чинить и делать так чтобы выглядело так, как тебе, а не ему нужно.

                                      Если без визуального никак — смотри в сторону CKEditor, с ним головной боли меньше намного.
                      2. Александр Котлов 09 марта 2014, 00:06 # 0
                        А картинки как в вики описано он вставлять умеет?

                        [Alt-текст]([[URL]] изображения "Заголовок изображения")
                        Такая конструкция у меня почему-то как ссылка отображается(

                        ЗЫ
                        Проверил, нет(
                        1. Василий Наумкин 09 марта 2014, 08:33 # 0
                          Смотри официальную документацию.
                          ![Alt text](https://file.modx.pro/files/8/5/3/85333575318f1fb2e7fe2881eb25559a.png "Optional title")
                          
                          1. Александр Котлов 09 марта 2014, 18:46 # 0
                            Rак всегда снимаю шляпу. В википедии забыли "!" (

                            Спасибо!
                        Добавление новых комментариев отключено.