Introducing the Markdown Easy Drupal module

Markdown is a text processing library that takes readable text and converts it into HTML. Started over 20 years ago, it is now a widely-used library that makes it easy for people to write text documents that can be easily and predictably converted into HTML.

Quick example - the Markdown syntax "this is **important**" converts to "this is important" after passing through a Markdown converter.

There are many "flavors" of Markdown today - most include the basic syntax and many include their version of "extended Markdown". Examples include Github-flavored Markdown and CommonMark.

Predictably, there have been Markdown-related Drupal contrib modules for a number of years, with the standard being the predictably named Markdown module. Started in 2008, it is currently used by about 5,000 Drupal sites (down from a high of more than 12,000 sites a few years ago).

Unfortunately, as of the publishing of this blog post, the current iteration of the Markdown module does not yet have a full release compatible with Drupal 10, although there are efforts ongoing to remedy this.

Why a new module?

DrupalEasy.com uses the Markdown syntax for some of its content. During our effort to upgrade DrupalEasy.com, the Markdown module became our last blocker to achieving that goal.

We took the time to review the current state of the Markdown module and its effort to be upgraded for Drupal 10, and in the end, we decided to pursue a simpler (in terms of module configuration,) less-time-consuming (in terms of contribution time,) and sustainable (in terms of ease of future upgrades) solution.

The existing Markdown module is configurable - really configurable. Some might say "too configurable".

One of the main configuration choices one has to make when using the Markdown module is choosing which Markdown library to utilize. The various open-source Markdown-processor libraries implement their own flavor of Markdown (like the Github and CommonMark libraries mentioned above). In fact, the Markdown module allows you to utilize multiple Markdown processor libraries. Once a library is selected, there are a myriad of additional configuration options available for each library and for each text format where the Markdown filter is utilized. Configuring the Markdown module in a secure manner is (in our experience) a bit of a chore.

I have no doubt that there are users of the Markdown module that require that level of control and fine-grained configuration. In those cases, the Markdown module is probably their best choice.

But, what about users who don't need that level of control? Users who just want to process Markdown formatted text into basic HTML with a minimum of fuss using a tried-and-true Markdown library. It is for these users that the Markdown Easy module was created.

What makes Markdown Easy different?

In short:

1. It is opinionated about the Markdown library - it uses CommonMark. Full stop.
2. It is opinionated about its configuration - it is configured to be as secure as possible.
3. It is easy to install and configure (see 1 and 2 above).

It was decided early on that the CommonMark library would be a dependency of Markdown Easy. It has more than 150 million installs on Packagist.org and is considered by many as the "gold standard" of Markdown libraries. In addition, it comes with the "Github-flavored Markdown" option as well. Selecting between these two "flavors" of Markdown is the only configuration option you have in Markdown Easy.

The module is preconfigured to be as secure as possible. Configured incorrectly, a Markdown library will output virtually any HTML tag - some that can be abused by bad actors. For example, the Markdown Easy module (by default) does not allow unsafe links or HTML tags to be processed (both of these options can be overridden with a Markdown Easy hook implementation). Additionally, validation of any text format utilizing the Markdown Easy filter requires that both the "Limit HTML" and "Convert line breaks" Drupal core filters be enabled and set to run in a prescribed order to ensure secure usage and consistent results (again, this can be overridden with a hook).

What features are planned for future versions of Markdown Easy?

Not many.

The goal is to have an easy-to-maintain (between major versions of Drupal core,) easy-to-configure (for site-builders,) and easy-to-customize (via Drupal hooks) module.

The only feature that we are currently interested in adding is the option of a GitLab-flavored Markdown library.

Is this module ready for prime-time?

We think so. In fact, the article that you're reading was written in Markdown and processed into HTML by the Markdown Easy module (with the exception of the logo - standard HTML was used for styling purposes).

Full documentation, including examples for overriding default validation and configuration, is available on drupal.org.

Markdown Easy's code base is primarily validation and automated test code. The filter plugin is 129 lines of code while validation and automated tests include over 700 lines of code.

We are using Drupal.org's Gitlab CI to run the tests in both Drupal 9 and Drupal 10 on every merge request and the module is covered by Drupal's security advisory policy.

We invite you to check it out and let us know what you think!