league/commonmark 1.3.0 Adds Full GFM Support!

league/commonmark adds Github-Flavored Markdown support

🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉
With the recent release of version 1.3.0, I'm excited to share that league/commonmark now offers full support for Github-Flavored Markdown!

(In fact, I believe it's the only Markdown parser for PHP that fully supports both CommonMark and GFM with 100% test coverage against the two relevant specs.)

Enabling GFM support is straightforward for most users - simply upgrade to version 1.3.0 and replace any usages of CommonMarkConverter in your code with the new GithubFlavoredMarkdownConverter class:

Before:

<?php
use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter([
    'html_input' => 'strip',
    'allow_unsafe_links' => false,
]);

echo $converter->convertToHtml('# Hello World!');

// <h1>Hello World!</h1>

After:

<?php
use League\CommonMark\GithubFlavoredMarkdownConverter;

$converter = new GithubFlavoredMarkdownConverter([
    'html_input' => 'strip',
    'allow_unsafe_links' => false,
]);

echo $converter->convertToHtml('# Hello World!');

// <h1>Hello World!</h1>

For more advanced usages, you might need to either:

  • Replace any calls to Environment::createCommonMarkEnvironment() with Environment::createGFMEnvironment(); or,
  • Register a new GithubFlavoredMarkdownExtension() in your existing environment

Refer to the documentation for more details.

What about those other league/commonmark-ext packages?

We've essentially brought the functionality of all of these packages directly into the core library:

  • league/commonmark-extras (basically was a meta-package for most of the GFM extensions below)
  • league/commonmark-ext-autolink
  • league/commonmark-ext-smartpunct
  • league/commonmark-ext-strikethrough
  • league/commonmark-ext-table
  • league/commonmark-ext-task-list
  • league/commonmark-ext-smartpunct
  • league/commonmark-ext-inlines-only

Users of those packages may continue to use them, but support for issues and future compatibility will not be provided. I strongly encourage you to switch to the built-in GFM support provided in 1.3.0 instead

Switching should be relatively painless for most people - the general gist is:

  • Upgrade to league/commonmark 1.3
  • Replace any references to the League\CommonMark\Ext\ namespace in your code to League\CommonMark\Extension\
  • Remove the deprecated packages from your composer.json

For the most part, all of the extensions were imported as-is into this codebase with a single code-level change to the namespace:

-namespace League\CommonMark\Ext\{extension-name-here};
+namespace League\CommonMark\Extension\{extension-name-here};

The only other significant changes made were to the Tables extension, but only to align it with the GFM spec.

More Information

If you'd like more information on this change, how it might impact you, or how to get started with GFM, please check out the following resources:

Hope you enjoy the 1.3.0 release - happy parsing!

Was this helpful?

About Colin O'Dell

Colin O'Dell

Colin O'Dell is a Senior Software Engineer at SeatGeek. In addition to being an active member of the PHP League and maintainer of the league/commonmark project, Colin is also a PHP docs contributor, conference speaker, and author of the PHP 7 Migration Guide.