league/commonmark is a Markdown parser for PHP which supports the full CommonMark spec. It is directly based the CommonMark JS reference implementation by John MacFarlane (@jgm).
While other Markdown parsers focus on speed, or try to enable a wide range of flavors, this parser will strive to match the C and JavaScript implementations of CommonMark to make a logical and similar API.
We will always focus on CommonMark compliance over speed, but performance improvements will definitely happen during efforts to reach v1.0.0 and afterwards.
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();
echo $converter->convertToHtml('# Hello World!');
// <h1>Hello World!</h1>The actual conversion process requires two steps:
- Parsing the Markdown input into an AST
- Rendering the AST document as HTML
You can do this yourself if you wish:
use League\CommonMark\DocParser;
use League\CommonMark\Environment;
use League\CommonMark\HtmlRenderer;
$environment = Environment::createCommonMarkEnvironment();
$parser = new DocParser($environment);
$htmlRenderer = new HtmlRenderer($environment);
$markdown = '# Hello World!';
$documentAST = $parser->parse($markdown);
echo $htmlRenderer->renderBlock($documentAST);
// <h1>Hello World!</h1>This approach allows you to access (and possibly modify) the AST before it's rendered.
You can add your own parsers and renderers by registering them with the Environment class.
The documentation contains additional details and some helpful examples to get you started. You can also reference the core CommonMark parsers/renderers as they use the same functionality available to you.
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.
The following table shows which versions of league/commonmark are compatible with which version of the CommonMark spec:
| league/commonmark | CommonMark spec | Notes |
|---|---|---|
| 0.5.x 0.4.0 |
0.13 | current spec (as of Dec 15 '14) |
| 0.3.0 | 0.12 | |
| 0.2.x | 0.10 | |
| 0.1.x | 0.01 |
This package is not part of CommonMark, but rather a compatible derivative.
Documentation can be found at commonmark.thephpleague.com.
$ ./vendor/bin/phpunitThis 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.phpWhile 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 both CommonMark and this project are considered stable. 0.x.x will be used until that happens.
SemVer will be followed closely.
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.
This code is a port of the CommonMark JS reference implementation which is written, maintained and copyrighted by John MacFarlane. This project simply wouldn't exist without his work.
league/commonmark is licensed under the BSD-3 license. See the LICENSE file for more details.