Github со вкусом Markdown + OSGi + dotCMS

Как CMS на основе Java, dotCMS обрабатывает множество различных вариантов использования для управления и доставки контента. Недавно нас спросили, может ли dotCMS предоставлять контент с уценкой Github. Мы подумали, что это будет отличным примером того, как легко расширить dotCMS с помощью плагинов OSGi. (Как примечание, этот блог — как видно на dotcms.com — на самом деле написан с использованием плагина).

• Просто возьми меня к исходному коду

уценка

Markdown — это анализатор текста в HTML, изначально написанный Джоном Грубером. Он предоставляет пользователю простой небольшой набор тегов разметки, которые анализируются и отображаются в виде стандартного HTML для использования браузерами или даже менее способными представлениями или окнами просмотра. Github Flavored Markdown , или GFM, предлагает несколько расширений для дальнейшего форматирования, включая поддержку зачеркивания, автоматического связывания URL, подсветки синтаксиса и таблиц. Из-за повсеместного использования github как ресурса кодирования GFM стал стандартом де-факто для комментирования. документация и другие инструменты онлайн-авторинга, которым нужна поддержка форматирования, но которые хотят ограничить «креативность».

Выбор библиотеки разбора Java Markdown

Существует множество различных библиотек Java Markdown, в том числе:

• Pegdown  — больше места, зависимости, медленнее, могут зависать
• Markdown4j  — приятно, хотя кажется заброшенным
• TxtMark  — маленький, быстрый, но не поддерживает расширения GFM

dotCMS решил использовать TxtMark от René Jeschke, который предлагает быструю автономную реализацию Markdown без внешних зависимостей. Так как TxtMark поддерживает только «стандартную» уценку, мы также реализовали дополнения, предложенные  Богданом Стефанеску  для дальнейшей ароматизации Github. Мы также добавили возможность подсветки синтаксиса кода, добавив атрибут класса в блок кода <code> (и используя  highlight.js )

Создание плагина OSGi

Большая часть контента, отображаемого в dotCMS, анализируется Apache Velocity. dotCMS предоставляет разработчикам точку расширения OSGi для подключения к Velocity и предоставляет пользовательские «Viewtools» Velocity, которые являются чистым Java и могут использоваться при рендеринге контента, страниц, шаблона или виджета (Viewtools можно рассматривать как эквивалент Velocity jsp taglib).

Для начала мы скопировали  пример Viewtool OSGi,  представленный в исходном коде dotCMS. Это дало нам основу для создания нашего плагина. Затем мы скопировали java-файлы txtmark в наш каталог плагинов src  ./src/main/java и добавили наш собственный пакет и реализацию Viewtool  MarkdownTool.java. Этот класс реализует org.apache.velocity.tools.view.tools.ViewTool интерфейс и предоставляет общедоступные методы веб-разработчикам для использования при отображении контента. Важным методом является  parse(String markdown)и принимает строку уценки, получает процессор уценки и возвращает нашу строку в виде размеченного HTML.

Наш финальный  MarkdownTool код может быть буквально таким же простым, как этот.

    /**
     * Parse a String for markdown
     * @param parse
     * @return
     * @throws Throwable
     */
    public String parse(String parse) throws Throwable {
        return Processor.process(parse, Configuration.builder().forceExtentedProfile().build());
    }

    public String getKey() {
        return "markdown";
    }

    public String getScope() {
        return "request";
    }

    public Object getInstance(Object initData) {
        MarkdownTool viewTool = new MarkdownTool();
        viewTool.init(initData);
        return viewTool;
    }

initializeServices(bundleContext);
registerViewToolService(bundleContext, new MarkdownToolInfo());

jar {
    manifest {
        name = 'Markdown Viewtool'
        instruction 'Bundle-Vendor', 'dotcms'
        instruction 'Bundle-Description', 'dotCMS - Markdown'
        instruction 'Bundle-DocURL', 'http://www.dotcms.com'
        instruction 'Bundle-Activator', 'com.dotcms.osgi.markdown.Activator'
        instruction 'DynamicImport-Package', '*'
        instruction 'Import-Package', '*;version=0'
    }
}

./gradlew clean jar

$markdown.parse("**Parse** *this* ~~string~~") 

**Parse** *this* ~~string~~

$markdown.parse($content.body)