PHP Markdown parser based on the CommonMark spec
- dev-master / 1.0.x-dev
- Fully support the CommonMark spec (100% compliance)
- Provide an extensible parser/renderer which users may customize as needed
- Continuously improve performance without sacrificing quality or compliance
- Match the official reference implementations of CommonMark
This project can be installed via Composer:
$ composer require league/commonmark
Note: See Versioning for important information on which version constraints you should use.
CommonMarkConverter class provides a simple wrapper for converting CommonMark to HTML:
use League\CommonMark\CommonMarkConverter; $converter = new CommonMarkConverter(); echo $converter->convertToHtml('# Hello World!'); // <h1>Hello World!</h1>
⚠️Security warning: If you will be parsing untrusted input from users, please consider setting the
allow_unsafe_links options. 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.
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.
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
- Symfony 2 & 3
- Symfony 4
- Twig Markdown extension
- Twig filter and tag
The PHP League offers useful extensions that add extra syntax and features:
league/commonmark-extras- Bundles the extensions below into a single dependency for convenience
league/commonmark-ext-autolink- Extension for league/commonmark which autolinks URLs, emails, and (optionally) @-mentions
league/commonmark-ext-smartpunct- Intelligently converts ASCII quotes, dashes, and ellipses to their Unicode equivalents
league/commonmark-ext-strikethrough- Adds support for
league/commonmark-ext-task-list(https://github.com/thephpleague/commonmark-ext-task-list) - Support for Github-style task lists
league/commonmark-ext-inlines-only- Renders inline text without paragraph tags or other block-level elements
league/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 Table Extension - Adds the ability to create tables in CommonMark documents.
- 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 (
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
This project aims to fully support the entire CommonMark spec. Other flavors of Markdown may work but are not supported. Any/all changes made to the spec or JS reference implementation should eventually find their way back into this codebase.
league/commonmark 0.19.0 and higher supports version 0.29 of the CommonMark spec.
(This package is not part of CommonMark, but rather a compatible derivative.)
$ composer test
This 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:
SemVer will be followed closely. 0.x.0 versions will introduce breaking changes to the codebase, so be careful which version constraints you use. It's highly recommended that you use Composer's caret operator to ensure compatibility; for example:
^0.18. This is equivalent to
0.x.y 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, minor spec changes, etc.) As a result, you might get slightly different HTML, but any custom code built onto this library will still function correctly.
If you're only using the
CommonMarkConverter class or
ConverterInterface to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like
>0.18, etc. I personally promise to never break this specific class in any future 0.x release.
While this package does work well, the underlying code should not be considered "stable" yet. The original spec and JS parser may undergo changes in the near future which will result in corresponding changes to this code. Any methods tagged with
@api are not expected to change, but other methods/classes might.
Major release 1.0.0 will be reserved for when either the CommonMark spec or this project are considered stable (see outstanding CommonMark spec issues). 0.x.y will be used until that happens.
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.
For now, I'd like to maintain similar logic as the JS reference implementation until everything is stable. I'll gladly accept any contributions which:
- Mirror fixes made to the reference implementation
- Optimize existing methods or regular expressions
- Fix issues with adhering to the spec examples
Major refactoring should be avoided for now so that we can easily follow updates made to the reference implementation. This restriction will likely be lifted once the CommonMark specs and implementations are considered stable.
Please see CONTRIBUTING for additional details.
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure with us.
We'd also like to extend our sincere thanks the following sponsors who support ongoing development of this project:
- RIPS Technologies for supporting this project with a complimentary RIPS SaaS license
- JetBrains for supporting this project with complimentary PhpStorm licenses
league/commonmark is licensed under the BSD-3 license. See the
LICENSE file for more details.