Dries Buytaert

Installing and configuring Markdown Easy for Drupal

This page is part of my digital garden. It is more like a notebook entry than a polished blog post. It's a space where I document learnings primarily for my own reference, yet share them in case they benefit others. Unlike my blog posts, these pages are works-in-progress and updated over time. Like tending to a real garden, I periodically refine its content. I welcome suggestions for improvements at dries@buytaert.net.

I recently installed Markdown Easy for Drupal and then upgraded from version 1.0 to 2.0.

I decided to document my steps in a public note in case they help others.

On my local machine, I run Drupal with DDEV. It sets up pre-configured Docker containers for the web server, database, and other required Drupal services. DDEV also installs Composer and Drush, which we will use in the steps below.

First, I installed version 2.0 of Markdown Easy using Composer:

ddev composer require drupal/markdown_easy

If you are upgrading from version 1.0, you will need to run the database updates so Drupal can apply any changes required by the new version. You can do this using Drush:

ddev drush updatedb

As explained in Switching to Markdown after 20 years of HTML, I want to use HTML and Markdown interchangeably. By default, Markdown Easy strips all HTML. This default approach is the safest option for most sites, but it also means you can't freely mix HTML tags and Markdown.

To change that behavior, I needed to adjust two configuration settings. These settings are not exposed anywhere in Drupal's admin interface, which is intentional. Markdown Easy keeps its configuration surface small to stay true to its "easy" name, and it leads with a secure-by-default philosophy. If you choose to relax those defaults, you can do so using Drush.

ddev drush config:set markdown_easy.settings skip_html_input_stripping 1

ddev drush config:set markdown_easy.settings skip_filter_enforcement 1

The skip_html_input_stripping setting turns off input stripping in the CommonMark Markdown parser, which means your HTML tags remain untouched while Markdown is processed.

The skip_filter_enforcement setting lets you turn off input stripping in Drupal itself. It allows you to disable the "Limit allowed HTML tags" filter without warnings from Markdown Easy.

You can enable just the first setting if you want Markdown to allow HTML but still let Drupal filter certain tags using the "Limit allowed HTML tags" filter. Or you can enable both if you want full control over your HTML with no stripping at either stage.

Just know that disabling HTML input stripping and disabling HTML filter enforcement can have security implications. Only disable these features if you trust your content creators and understand the risks.

Next, I verified my settings:

ddev drush config:get markdown_easy.settings

You should see:

skip_html_input_stripping: true
skip_filter_enforcement: true

Finally, clear the cache:

ddev drush cache-rebuild

Next, I updated my existing Markdown text format. I went to /admin/config/content/formats/ and made the following changes:

  • Set the Markdown flavor to Smorgasbord.
  • Disabled the "Limit allowed HTML tags and correct faulty HTML" filter.
  • Disabled the "Convert line breaks into HTML" filter.

That's it!