league/commonmark is a highly-extensible PHP Markdown parser created by Colin O'Dell which supports the full CommonMark spec. It is based on the CommonMark JS reference implementation by John MacFarlane (@jgm).
This project can be installed via Composer:
$ composer require league/commonmarkThe CommonMarkConverter class provides a simple wrapper for converting CommonMark to HTML:
use League\CommonMark\CommonMarkConverter;
$converter = new CommonMarkConverter([
'html_input' => 'strip',
'allow_unsafe_links' => false,
]);
echo $converter->convertToHtml('# Hello World!');
// <h1>Hello World!</h1>Please note that only UTF-8 and ASCII encodings are supported. If your Markdown uses a different encoding please convert it to UTF-8 before running it through this library.
🔒 If you will be parsing untrusted input from users, please consider setting the html_input and allow_unsafe_links options per the example above. See https://commonmark.thephpleague.com/security/ for more details. If you also do choose to allow raw HTML input from untrusted users, considering using a library (like HTML Purifier) to provide additional HTML filtering.
Full documentation on advanced usage, configuration, and customization can be found at commonmark.thephpleague.com.
Information on how to upgrade to newer versions of this library can be found at https://commonmark.thephpleague.com/releases.
- CakePHP 3
- Drupal 7 & 8
- Laravel 4 & 5
- Sculpin
- Symfony 2 & 3
- Symfony 4
- Twig Markdown extension
- Twig filter and tag
You can easily add support for Github-Flavored Markdown by installing the league/commonmark-extras package, which includes bundles all of the extensions listed below:
| Feature | Package Name | Description |
|---|---|---|
| Autolinks | league/commonmark-ext-autolink |
Automatically links URLs, emails, and (optionally) @-mentions without needing to use <...> |
| Smart Punctuation | league/commonmark-ext-smartpunct |
Intelligently converts ASCII quotes, dashes, and ellipses to their Unicode equivalents |
| Strikethrough | league/commonmark-ext-strikethrough |
Adds support for ~~strikethrough~~ syntax |
| Task Lists | league/commonmark-ext-task-list |
Support for Github-style task lists |
| Tables | league/commonmark-ext-table |
GFM-style tables |
league/commonmark-ext-inlines-only- Renders inline text without paragraph tags or other block-level elementsleague/commonmark-ext-external-link- Mark external links, make them open in new windows, etc.
You can add them to your project or use them as examples to develop your own custom features.
Custom parsers/renderers can be bundled into extensions which extend CommonMark. Here are some that you may find interesting:
- CommonMark Attributes Extension - Adds a syntax to define attributes on the various HTML elements.
- Alt Three Emoji An emoji parser for CommonMark.
- Sup Sub extensions - Adds support of superscript and subscript (
<sup>and<sub>HTML tags)
Others can be found on Packagist under the commonmark-extension package type.
If you build your own, feel free to submit a PR to add it to this list!
Check out the other cool things people are doing with league/commonmark: https://packagist.org/packages/league/commonmark/dependents
SemVer is followed closely. Minor and patch releases should not introduce breaking changes to the codebase; however, they might change the resulting AST or HTML output of parsed Markdown (due to bug fixes, spec changes, etc.) As a result, you might get slightly different HTML, but any custom code built onto this library should still function correctly.
Any classes or methods marked @internal are not intended for use outside of this library and are subject to breaking changes at any time, so please avoid using them.
When a new minor version (1.x) is released, the previous one will continue to receive security and bug fixes for at least 3 months.
When a new major version is released (1.0, 2.0, etc), the previous one (0.19.x) will receive bug fixes for at least 3 months and security updates for 6 months after that new release comes out.
(This policy may change in the future and exceptions may be made on a case-by-case basis.)
Professional support, including notification of new releases and security updates, is available through a Tidelift Subscription.
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure with us.
If you encounter a bug in the spec, please report it to the CommonMark project. Any resulting fix will eventually be implemented in this project as well.
Contributions to this library are welcome, especially ones that:
- Improve usability or flexibility without compromising our ability to adhere to the CommonMark spec
- Mirror fixes made to the reference implementation
- Optimize performance
- Fix issues with adhering to the CommonMark spec
Major refactoring to core parsing logic should be avoided if possible so that we can easily follow updates made to the reference implementation. That being said, we will absolutely consider changes which don't deviate too far from the reference spec or which are favored by other popular CommonMark implementations.
Please see CONTRIBUTING for additional details.
$ composer testThis will also test league/commonmark against the latest supported spec.
You can compare the performance of league/commonmark to other popular parsers by running the included benchmark tool:
$ ./tests/benchmark/benchmark.phpThis code is partially based on the CommonMark JS reference implementation which is written, maintained and copyrighted by John MacFarlane. This project simply wouldn't exist without his work.
We'd also like to extend our sincere thanks the following sponsors who support ongoing development of this project:
- Tidelift for offering support to both the maintainers and end-users through their professional support program
- RIPS Technologies for supporting this project with a complimentary RIPS SaaS license
- JetBrains for supporting this project with complimentary PhpStorm licenses
Are you interested in sponsoring development of this project? Make a pledge of $10 or more and we'll include your name on our website!
league/commonmark is licensed under the BSD-3 license. See the LICENSE file for more details.
This project is primarily maintained by Colin O'Dell. Members of the PHP League Leadership Team may occasionally assist with some of these duties.
Tidelift helps make open source sustainable for maintainers while giving companies
assurances about security, maintenance, and licensing for their dependencies.