Extensions Overview
Extensions provide a simple way to add new syntax and features to the CommonMark parser.
Included Extensions
Starting with version 1.3.0, this library includes several extensions to support GitHub Flavored Markdown (GFM) and
many other common use-cases. Most of these extensions started out as 3rd-party community based extensions that have
since been officially adopted by this library in an effort to ensure future compatibility and to provide an easy way
to enhance your experience out-of-the-box depending on your specific use-cases.
| Extension | Purpose | Version Introduced | GFM |
|---|---|---|---|
| Attributes | Add HTML attributes (like id and class) from within the Markdown content |
1.5.0 |
|
| Autolinks | Enables automatic linking of URLs within text without needing to wrap them with Markdown syntax | 1.3.0 |
|
| Default Attributes | Easily apply default HTML classes using configuration options to match your site’s styles | 2.0.0 |
|
| Description Lists | Create <dl> description lists using Markdown Extra’s syntax |
2.0.0 |
|
| Disallowed Raw HTML | Disables certain kinds of HTML tags that could affect page rendering | 1.3.0 |
|
| Embed | Embed rich content (like videos, tweets, and more) from other websites | 2.3.0 |
|
| External Links | Tags external links with additional markup | 1.3.0 |
|
| Footnotes | Add footnote references throughout the document and show a listing of them at the bottom | 1.5.0 |
|
| Front Matter | Parses YAML front matter from your Markdown input | 2.0.0 |
|
| GitHub Flavored Markdown | Enables full support for GFM. Automatically includes the extensions noted in the GFM column (though you can certainly add them individually if you wish): |
1.3.0 |
|
| Heading Permalinks | Makes heading elements linkable | 1.4.0 |
|
| Inlines Only | Only includes standard CommonMark inline elements - perfect for handling comments and other short bits of text where you only want bold, italic, links, etc. | 1.3.0 |
|
| Mentions | Easy parsing of @mention and #123-style references |
1.5.0 |
|
| Strikethrough | Allows using tilde characters (~~) for ~strikethrough~ formatting |
1.3.0 |
|
| Tables | Enables you to create HTML tables | 1.3.0 |
|
| Table of Contents | Automatically inserts links to the headings at the top of your document | 1.4.0 |
|
| Task Lists | Allows the creation of task lists | 1.3.0 |
|
| Smart Punctuation | Intelligently converts ASCII quotes, dashes, and ellipses to their fancy Unicode equivalents | 1.3.0 |
Usage
You can enable extensions by simply calling ->addExtension() on the Environment.
In an effort to streamline the extensions used in GitHub Flavored Markdown (GFM), a special extension named
GithubFlavoredMarkdownExtension can be used that will automatically add all the extensions checked in the GFM
column above for you:
use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\GithubFlavoredMarkdownExtension;
use League\CommonMark\MarkdownConverter;
// Define your configuration, if needed
$config = [];
// Configure the Environment with all the extensions you need
$environment = new Environment($config);
$environment->addExtension(new CommonMarkCoreExtension());
$environment->addExtension(new GithubFlavoredMarkdownExtension());
$converter = new MarkdownConverter($environment);
echo $converter->convert('Hello World!');
Or maybe you only want a subset of GFM extensions, plus the Smart Punctuation extension:
use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\Autolink\AutolinkExtension;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\DisallowedRawHtml\DisallowedRawHtmlExtension;
use League\CommonMark\Extension\SmartPunct\SmartPunctExtension;
use League\CommonMark\Extension\Strikethrough\StrikethroughExtension;
use League\CommonMark\Extension\Table\TableExtension;
use League\CommonMark\MarkdownConverter;
// Define your configuration, if needed
$config = [];
// Configure the Environment with all the CommonMark parsers/renderers
$environment = new Environment($config);
$environment->addExtension(new CommonMarkCoreExtension());
// Add the other extensions you need
$environment->addExtension(new AutolinkExtension());
$environment->addExtension(new DisallowedRawHtmlExtension());
$environment->addExtension(new SmartPunctExtension());
$environment->addExtension(new StrikethroughExtension());
$environment->addExtension(new TableExtension());
$converter = new MarkdownConverter($environment);
echo $converter->convert('Hello World!');
The extension system makes it easy to mix-and-match extensions to fit your needs.
Writing Custom Extensions
See the Custom Extensions page for details on how you can create your own custom extensions.