CommonMark by CartThrob

CommonMark by CartThrob Version 1.0.0

CommonMark

Utilize different markdown flavors in your templates or text fields

REQUIREMENTS

This add-on requires ExpressionEngine 6 and PHP 7.1.

INSTALLATION

  1. Copy commonmark folder to your system/user/addons folder.
  2. On your EE backend, navigate to Developer > Addons (yoursite.com/admin.php?/cp/addons).
  3. Scroll to Third Party Add-Ons.
  4. Find CommonMark and click Install.
  5. Copy commonmark.php to your system/user/config folder

SETTINGS

All settings are managed in system/user/config/commonmark.php (see Installation). The commonmark.php file should return an array like:

$config = [
    [
        'name' => 'default',
        'default' => true,
        'parser' => 'github',
        'config' => [
            'renderer' => [
                'block_separator' => "\n",
                'inner_separator' => "\n",
                'soft_break'      => "\n",
            ],
            'html_input'         => 'escape',
            'allow_unsafe_links' => false,
            'max_nesting_level'  => PHP_INT_MAX,
            'slug_normalizer'    => [
                'max_length' => 255,
            ],
        ]
    ],
    [
        'name' => 'another_one',
        'default' => false,
        'parser' => 'commonmark',
        'extensions' => [
            'description_list',
            'front_matter',
        ],
        'config' => [
            'html_input'         => 'escape',
            'allow_unsafe_links' => false,
            'max_nesting_level'  => PHP_INT_MAX,
            'slug_normalizer'    => [
                'max_length' => 255,
            ],
        ],
    ],
];

Configs must have 4 parameters:

  • name (string): Name of the config you are setting up. This can be any string.
  • default (boolean): Indicates the default configuration to use when parsing. When using this in a fieldtype, this will be the configuration that is used.
  • parser (string): Name of the parser. See Parsers for more information
  • config (array): Config to set up parser. See the appropriate parser's documentation

In addition, you can add the following optional parameters:

  • extensions (array): If the selected parser supports extensions, include their names here. See Extension for more information on out-of-the-box supported extensions.

Parsers

Currently, the CommonMark plugin supports the following parsers:

  • commonmark: The standard CommonMark core extension. Documentation

  • github: The Github Flavored Markdown core extension. Documentation

Extensions

  • attributes: Add HTML attributes (like id and class) from within the Markdown content. Documentation
  • autolink: The AutolinkExtension adds GFM-style autolinking. It automatically links URLs and email addresses even when the CommonMark <...> autolink syntax is not used. Documentation
  • description_list: The DescriptionListExtension adds Markdown Extra-style description lists to facilitate the creation of
    ,
    , and
    HTML using Markdown. Documentation
  • front_matter: The FrontMatterExtension adds the ability to parse YAML front matter from the Markdown document and include that in the return result. Documentation
  • strikethrough: This extension adds support for GFM-style strikethrough syntax. It allows users to use ~~ in order to indicate text that should be rendered within tags. Included by default with the GithubFlavored Markdown extension. Documentation
  • table: The TableExtension adds the ability to create tables in CommonMark documents. Documentation[https://commonmark.thephpleague.com/2.2/extensions/tables/]
  • task_list: This extension adds support for GFM-style task lists. Included by default with the GithubFlavored Markdown extension. Documentation

USAGE

In Text Fieldtype

When creating a field and utilizing a fieldtype that utilizes typography, select CommonMark under Text Formatting:

An example of selecting CommonMark

When rendering the field in your template, it will automatically render using the default config in your system/user/config/commonmark.php config file.

In Templates

You can also use the commonmark plugin inside of a template to render any markdown according to your selected configuration:

{exp:commonmark}

# Title

[Markdown Guide](https://www.markdownguide.org/basic-syntax)

{/exp:commonmark}

To use a particular configuration, include the config parameter on your tag:

{!-- This will use your default configuration --}
{exp:commonmark}

# Title

[Markdown Guide](https://www.markdownguide.org/basic-syntax)

{/exp:commonmark}

{!-- This will use a configuration called another_one --}
{exp:commonmark config="another_one"}

# Title

[Markdown Guide](https://www.markdownguide.org/basic-syntax)

{/exp:commonmark}

Buy Now