Advanced configuration

The Markdown Easy module is designed to be configured as securely as possible by default. Advanced configuration of the Markdown Easy module is required to override the default security-related configuration.

Overriding Markdown processor configuration

By default, the Markdown Easy module utilizes the CommonMark library in its recommended, secure, configuration. To override this configuration, implement hook_markdown_easy_config_modify() in a custom module.

Examples of implementing this hook to allow HTML and unsafe links:

1.x branch

use League\CommonMark\MarkdownConverter;

/**
 * Implements hook_markdown_easy_config_modify().
 */
function MY_MODULE_markdown_easy_config_modify(MarkdownConverter &$converter): void {
  $converter = new CommonMarkConverter([
    // Configure the Markdown processor to be not-so-secure.
    'html_input' => 'allow',
    'allow_unsafe_links' => TRUE,
  ]);
}

2.x branch

The 2.x branch of the module changed the implementation of this hook.

/**
 * Implements hook_markdown_easy_config_modify().
 */
function MY_MODULE_markdown_easy_config_modify(array &$config): void {
  // Configure the Markdown processor to be not-so-secure.
  $config['html_input'] = 'allow';
  $config['allow_unsafe_links'] = TRUE;
}

Modifying the Markdown (CommonMark) environment

Starting in the 2.x branch of Markdown Easy, additional CommonMark extensions can be added via hook_markdown_easy_environment_modify(). For example:  

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\Strikethrough\StrikethroughExtension;

/**
 * Implements hook_markdown_easy_environment_modify().
 */
function MY_MODULE_markdown_easy_environment_modify(Environment &$environment): void {
  $environment->addExtension(new StrikethroughExtension());
}

Overriding Markdown Easy validation

By default, the Markdown Easy module enforces a secure, recommended configuration of any text format where the Markdown Easy filter is enabled. This includes:

1. Requiring that the Convert line breaks into HTML and Limit allowed HTML tags and correct faulty HTML filters to be enabled to run after the "Markdown Easy" filter.
2. Requiring that the Convert line breaks into HTML filter be run after the Limit allowed HTML tags and correct faulty HTML filter.

Advanced use cases of Markdown Easy module may require these requirements to be waived. To do so, implement the following hook in a custom module:

/**
 * Implements hook_form_FORM_ID_alter().
 */
function MY_MODULE_form_filter_format_form_alter(array &$form, FormStateInterface $form_state, $form_id): void {
  // Disable the markdown_easy validation to allow potentially insecure
  // configurations.
  $key = array_search('_markdown_easy_filter_format_edit_form_validate', $form['#validate']);
  if ($key !== FALSE) {
    unset($form['#validate'][$key]);
  }
}

To implement the hooks shown above in a custom module, create a new custom module (using drush generate is easiest) and change MY_MODULE in the examples above to the machine name of the custom module you created and add the hook(s) in your module’s MY_MODULE.module file.

Power-user modes (version 2.0.x only)

Markdown Easy can be configured with no guardrails for users who are comfortable with Markdown syntax and understand the risks. There are two options for removing guardrails:

1. Skip filter enforcement - by enabling this option, Markdown Easy will no longer complain if the "Limit allowed HTML tags and correct faulty HTML" text filter is no longer enabled. 
2. Skip HTML input stripping - by enabling this option, HTML tags will be allowed to pass through the Markdown processor. 

Both options can be enabled by manually updating the markdown_easy.settings configuration of the module. For example:

skip_filter_enforcement: true
skip_html_input_stripping: true

These settings are not available through the Drupal admin UI, they can only be set via the configuration system.

The drush command line tool provides a handy way to accomplish this, which can be particularly useful in development environments. For example, to skip filter enforcement: 

drush config:set markdown_easy.settings skip_filter_enforcement 1