General usage

General usage documentation for the Markdown Easy module.

Installation

Install as you would normally install a contributed Drupal module. See: https://www.drupal.org/node/895232 for further information.

Configuration (1.x branch)

The Markdown Easy module automatically creates a "Markdown" text format when enabled. Feel free to customize.

To add a Markdown Easy text filter to an existing text format:

• Select the "Markdown Easy" text filter.
• Select "Standard Markdown" or "GitHub-flavored Markdown" in the text filter's settings on the text format's configuration page.
  • "Standard Markdown" includes support for italics, bold, images, links, lists, code, block quotes, headings, and horizontal rules.
  • "GitHub-flavored Markdown" includes everything in "Standard Markdown" plus support for footnotes and description lists.
• Enable and configure the "Limit allowed HTML tags and correct faulty HTML" filter to run after the Markdown Easy filter. Without this step, the text format will allow all HTML tags.
• Enable and configure the "Convert line breaks into HTML" filter to run after the Markdown Easy filter and the "Limit allowed HTML tags and correct faulty HTML" filter.
• For best results, at a minimum, text formats utilizing the Markdown Easy filter should be configured as follows:

  

• Markdown Easy requires (via validation) that it be configured with both the "Convert line breaks into HTML" and "Limit allowed HTML tags and correct faulty HTML" filters enabled to run after Markdown Easy. This can be overridden (at your peril) by removing the validation handler. See the Advanced configuration documentation for more information.
• Markdown Easy requires (via validation) that the "Convert line breaks into HTML" filter be run after the "Limit allowed HTML tags and correct faulty HTML" for best results. This can be overridden (at your peril) by removing the validation handler. See the Advanced configuration documentation for more information.

Configuration (2.x branch)

The Markdown Easy module automatically creates a "Markdown" text format when enabled. Feel free to customize.

To add a Markdown Easy text filter to an existing text format:

• Select the "Markdown Easy" text filter.
• Select "Standard Markdown", "GitHub-flavored Markdown", or "Markdown Smörgåsbord" in the text filter's settings on the text format's configuration page.
  • "Standard Markdown" includes support for italics, bold, images, links, lists, code, block quotes, headings, and horizontal rules.
  • "GitHub-flavored Markdown" includes everything in "Standard Markdown" plus support for autolinks, disallowed raw HTML, strikethrough, tables, and task lists. 
  • "Markdown Smörgåsbord" includes everything in "GitHub-flavored Markdown" plus support for footnotes and description lists.
• Enable and configure the "Limit allowed HTML tags and correct faulty HTML" filter to run after the Markdown Easy filter. Without this step, the text format will allow all HTML tags.
• Markdown Easy requires (via validation) that it be configured with both the "Limit allowed HTML tags and correct faulty HTML" filters enabled to run after Markdown Easy. This can be overridden (at your peril) - see the Advanced configuration documentation for more information.

Additional information

• The Markdown Easy text filter is configured to run with the following security-related settings by default:
  • html_input: strip
  • allow_unsafe_links: false
• See https://commonmark.thephpleague.com/2.4/security/ for more info. To override these settings, or to customize the configuration of the Markdown processor, utilize hook_markdown_easy_config_modify(). See the Advanced configuration documentation for more information.
• Additional CommonMark extensions can be added via hook_markdown_easy_environment_modify(). See the Advanced configuration documentation for more information.
• Note that the Markdown Easy module is currently not compatible with the Smart Trim module.

Tip for migrating from Markdown module

• The Markdown module allows the site-builder to install multiple Markdown processors, therefore, prior to installing Markdown Easy, if the league/commonmark parser is already installed, it should be removed (as Markdown Easy uses the latest version and Markdown does not).

  composer remove league/commonmark

Code highlight with Prism.js

Markdown Easy works with Prism.js and potentially other code highlighters.

1. Test Markdown Easy and make sure the formatter is working before doing any modifications
2. Install and enable Prism module and the respective libraries
3. Within the Markdown text format, enable Prism.js filter
4. Prism.js should be placed after "Markdown Easy" and before "Limit allowed HTML tags and correct faulty HTML" and "Convert line breaks into HTML".
5. Add the following markup to the allowed HTML tags list: <pre><code class>
6. To use syntax highlight, use the following Markdown markup (note the language definition tag at the top):  
   

   ```javascript
   
   //This is a sample JavaScript code
   let output = "Hello World!"
   document.write(let);
   
   ```