Adobe

Markdown in AEM with Flexmark

Wall Of Books

Markdown is a light markup language with text-based syntax which can be converted to HTML, PDFs or any number of different styled formats. Markdown is a popular format for text-heavy content such as documentation, wiki content and comments as it is easy to maintain and read the content without the added complexity of including formatting.

Unfortunately, AEM did not provide a mechanism to interact with Markdown content, nor were any of the Java markdown libraries compatible with OSGi. Recently, I worked with the Flexmark team to produce an OSGi bundle version of the Flexmark markdown library.

The Digital Essentials, Part 3
The Digital Essentials, Part 3

Developing a robust digital strategy is both a challenge and an opportunity. Part 3 of the Digital Essentials series explores five of the essential technology-driven experiences customers expect, which you may be missing or not fully utilizing.

Get the Guide

Now that this library is released, integrating markdown content into AEM is an easy process.

Using Flexmark in AEM

To use the Flexmark library in AEM, first you need to get the bundle installed. It can either be downloaded directly from Maven Central (not recommended) or integrated into your Content Package POM with the following:

<!-- within /project/dependencies -->
<dependency>
  <groupId>org.jsoup</groupId>
  <artifactId>jsoup</artifactId>
  <version>1.11.3</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>com.vladsch.flexmark</groupId>
  <artifactId>flexmark-osgi</artifactId>
  <version>0.34.22</version>
  <scope>provided</scope>
</dependency>
<!-- within /project/build/plugins/plugin (content-package-maven-plugin) -->
<embedded>
  <groupId>org.jsoup</groupId>
  <artifactId>jsoup</artifactId>
  <target>/apps/myapp/install</target>
</embedded>
<embedded>
  <groupId>com.vladsch.flexmark</groupId>
  <artifactId>flexmark-osgi</artifactId>
  <target>/apps/myapp/install</target>
</embedded>

Once the bundle is installed you can then use the Flexmark API to retrieve and leverage the Markdown content from the AEM repository, for example using a Sling Model like this one which retrieves Markdown content from the property markdownfield and converts the Markdown content to HTML:

package com.myorg.site.models;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.models.annotations.Model;
import org.apache.sling.models.annotations.injectorspecific.Self;
import com.vladsch.flexmark.ast.Node;
import com.vladsch.flexmark.html.HtmlRenderer;
import com.vladsch.flexmark.parser.Parser;
import com.vladsch.flexmark.util.options.MutableDataSet;
@Model(adaptables = Resource.class)
public class DiscussionMarkdownModel {
    @Self
    private Resource resource;
    public String getHtml() {
        MutableDataSet options = new MutableDataSet();
        Parser parser = Parser.builder(options).build();
        HtmlRenderer renderer = HtmlRenderer.builder(options).build();
        Node node = parser.parse(resource.getValueMap().get("markdownfield", String.class));
        return renderer.render(node);
    }
}

With the new Flexmark OSGi bundle, integrating Markdown in AEM is painless, as we can see in this simple example.
Robert Munteanu is also working on a Sling Resource Provider backed by Markdown files, which is an interesting concept if someone wanted to do something like publish documentation in Markdown, but display it on a site with the dynamic, marketing features AEM. So who knows, maybe Adobe could convert their documentation site into Markdown + AEM?
EDIT – 31-09-2018 – Indicating that JSoup is also required.

About the Author

Dan is a certified Adobe Digital Marketing Technologist, Architect, and Advisor, having led multiple successful digital marketing programs on the Adobe Experience Cloud. He's passionate about solving complex problems and building innovative digital marketing solutions. Dan is a PMC Member of the Apache Sling project, frequent Adobe Beta participant and committer to ACS AEM Commons, allowing a unique insight into the cutting edge of the Adobe Experience Cloud platform.

More from this Author

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Subscribe to the Weekly Blog Digest:

Sign Up