Markdown Easy

A simple Markdown text filter for Drupal that converts Markdown syntax to HTML using the league/commonmark library.

markdown_easy
615 sites
22
drupal.org
api utility
markdown text format filter content formatting commonmark github markdown
Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10, 9 v2.0.0
composer require 'drupal/markdown_easy:^2.0'

Overview

Markdown Easy is a straightforward Drupal text filter module designed to convert Markdown syntax into HTML. It leverages the powerful league/commonmark PHP library for parsing and provides minimal configuration through the Drupal admin interface.

The module offers three distinct Markdown "flavors" to suit different needs: Standard Markdown (CommonMark specification), GitHub-flavored Markdown (with tables, strikethrough, autolinks, and task lists), and Markdown Smörgåsbord (adding footnotes and description lists). Security is prioritized by default with HTML input stripping and unsafe link blocking.

When installed, Markdown Easy automatically creates a pre-configured "Markdown" text format. For security, it enforces that the Drupal core "Limit allowed HTML tags and correct faulty HTML" filter runs after the Markdown Easy filter to prevent XSS attacks.

Features

  • Three Markdown flavor options: Standard Markdown (CommonMark), GitHub-flavored Markdown, and Markdown Smörgåsbord with extended features
  • Automatic creation of a pre-configured 'Markdown' text format upon module installation
  • Security by default: HTML input stripping and unsafe link blocking enabled out of the box
  • Validation enforcement requiring the 'Limit allowed HTML tags' filter to run after Markdown Easy
  • Warning system that alerts administrators when required HTML tags are missing from the allowed tags list
  • Table alignment support with automatic CSS class injection for left, center, and right aligned columns
  • Extensibility through two hooks: hook_markdown_easy_config_modify() for configuration and hook_markdown_easy_environment_modify() for adding Markdown extensions
  • Runtime status checks that report insecure text format configurations on the Status Report page
  • Compatibility warning when deprecated 'Convert line breaks into HTML' filter is enabled

Use Cases

Technical Documentation Sites

Enable content editors to write technical documentation using familiar Markdown syntax. Use GitHub-flavored Markdown for code blocks with syntax highlighting support, tables for data presentation, and task lists for checklists. The Smörgåsbord flavor adds footnotes for citations and references.

Developer-Friendly Blog Platform

Create a blog where developers can write posts in Markdown rather than WYSIWYG editors. The familiar syntax reduces friction for technical writers who regularly use Markdown in their workflows (README files, GitHub issues, etc.).

Migrating from Static Site Generators

Organizations moving from Jekyll, Hugo, or other Markdown-based static site generators to Drupal can preserve their existing Markdown content without conversion. Editors can continue using the same syntax they're familiar with.

Headless CMS with Markdown Storage

For headless Drupal implementations where content is consumed by frontends that handle their own Markdown rendering, store raw Markdown in text fields and use Markdown Easy for preview in the Drupal admin.

Adding Custom Markdown Extensions

Developers can extend the built-in flavors by implementing hook_markdown_easy_environment_modify() to add any CommonMark extension from the ecosystem, such as Mentions, Smart Punctuation, or custom extensions.

Tips

  • Use the 'Markdown Smörgåsbord' flavor for the most complete feature set including footnotes and description lists
  • Always enable 'Limit allowed HTML tags' after Markdown Easy for proper security - this prevents XSS attacks
  • Check the Status Report page (/admin/reports/status) for warnings about insecurely configured text formats
  • When adding new HTML elements, refer to the filter tips displayed on the text format configuration page for the exact tags and attributes needed
  • Implement hook_markdown_easy_config_modify() to customize footnote styling or table alignment class names
  • For advanced customization, use hook_markdown_easy_environment_modify() to add any CommonMark extension from https://commonmark.thephpleague.com/2.6/extensions/overview/
  • Table alignment (left, center, right) automatically applies CSS classes that can be styled in your theme

Technical Details

Hooks 2
hook_markdown_easy_config_modify

Allows modules to modify the Markdown converter configuration before processing. This can be used to change security settings like html_input and allow_unsafe_links, or to customize footnote and table rendering options.

hook_markdown_easy_environment_modify

Allows modules to modify the Markdown environment after the base extensions are loaded. This can be used to add additional CommonMark extensions not included in the built-in flavors.

Troubleshooting 8
Text format shows error: 'The Markdown Easy filter needs to be placed before the Limit allowed HTML tags filter'

Adjust the filter weights on the text format configuration page. Ensure Markdown Easy has a lower weight (runs first) than the 'Limit allowed HTML tags' filter. The 'Limit allowed HTML tags' filter must be enabled and configured to run after Markdown Easy.

Markdown syntax is not being converted to HTML

Verify that the Markdown Easy filter is enabled in the text format being used. Check that the text format is assigned to the field and that users have permission to use that text format.

Some Markdown elements (tables, strikethrough, etc.) are not rendering

Ensure you've selected the appropriate Markdown flavor (GitHub-flavored for tables/strikethrough, Smörgåsbord for footnotes). Also verify that the corresponding HTML tags are included in the 'Limit allowed HTML tags' filter's allowed list.

Warning message about missing HTML tags appears when saving text format

Add the recommended HTML tags and attributes to the 'Limit allowed HTML tags' filter. The warning lists exactly which tags are needed for full compatibility with your selected Markdown flavor.

HTML tags in Markdown content are being stripped unexpectedly

By default, Markdown Easy strips HTML input for security. If you need to allow HTML, either set skip_html_input_stripping to true in configuration, or implement hook_markdown_easy_config_modify() to set html_input to 'allow'.

Status report shows 'Text format configured insecurely' warning

Enable the 'Limit allowed HTML tags' filter on the affected text format and ensure it runs after the Markdown Easy filter. This is a security requirement to prevent XSS attacks.

Upgrading from Markdown Easy 1.x causes line break issues

Version 2.x no longer requires the 'Convert line breaks into HTML' filter. Disable it and add <p> and <br> to the allowed HTML tags. Note that 1.x did not follow the Markdown spec for line breaks, so existing content may render differently.

Conflict with the Markdown module (drupal/markdown)

If you previously had the Markdown module installed with league/commonmark, remove the older version first: composer remove league/commonmark, then install Markdown Easy. Markdown Easy requires a newer version of the library.

Security Notes 6
  • By default, Markdown Easy runs with html_input: strip and allow_unsafe_links: false for maximum security
  • The module enforces that 'Limit allowed HTML tags' filter runs after Markdown Easy to sanitize the converted HTML output
  • Disabling filter enforcement (skip_filter_enforcement) or HTML stripping (skip_html_input_stripping) may expose your site to XSS vulnerabilities
  • The module displays runtime warnings on the Status Report page for any text formats configured insecurely
  • When using hooks to modify security settings, ensure you understand the implications for your site's security posture
  • The security coverage on drupal.org is 'covered', meaning this module is reviewed by the Drupal Security Team