Best Markdown libraries for PHP
Markdown is a light-weight markup language that is very popular, and is used widely in various applications from simple comment in a blog, to blog posts, to entire web sites built on it. The simplicity of the markup language makes it readable even without rendering as they are plain-text files, and the versatility of it means the text can be converted to HTML, PDF, Rich-Text files, and more.
In PHP, libraries such as Parsedown, CommonMark, PHP Markdown, and cebe/markdown each offer features, performance, and extensibility in different calibers. This article compares these four libraries with performance benchmarks, how easy it is to extend it, and different features and characteristics of them.
The original Markdown implementation was evolved to CommonMark and GitHub-Flavored Markdown, that offer features such as better code blocks, tables, and other features that were not in the original specification.
Not all Markdown libraries produce equal output: Some libraries may not recognize certain syntax features, and some may not even commit to a specific spec such as CommonMark or GFM. However, all libraries at least support the original syntax by John Gruber, and most widely used ones such as table syntax and code block syntax.
Parsedown
Parsedown is one of the most popular markdown libraries for PHP, written by Emanuil Rusev. It currently has over 13,000 GitHub stars, and over 75 million downloads on Packagist to date. It is used in several static CMS software, Laravel < 6, and over 600 other projects as reported on Packagist.
Parsedown supports most of the Common Mark syntax, but not all of them. It is a highly opinionated library that deliberately picks some of the most used features of Markdown syntax, and open itself for extension to the lesser used features.
Parsedown stands out of the competition as it is one of the simplest implementations, and is the fastest Markdown library. The entire Parsedown class is just a single file of nearly 2000 lines of code (including comments and spacing), and it is quite easy to use.
$parser = new Parsedown();
echo $parser->text('# Hello World!');
// "<h1>Hello World!</h1>"Parsedown does not support extensions, plugins, or hooks of any sort. The Parsedown class is open for extension with a child class that extends Parsedown, and all modifications can be done there, be it a new regular expression, or modifications to the abstract syntax tree.
There is also a Parsedown Extra project that provides support for some of the missing Markdown Extra features such as foot notes and definition lists.
CommonMark
CommonMark is a highly extensible and modern markdown library, written by Colin O'Dell, and several contributors.
CommonMark is used as the Markdown processor by choice since Laravel 6, and has over 1,700 GitHub stars, 31 million+ downloads reported on Packagist, and over 250 projects declaring it as a dependency.
CommonMark supports the complete CommonMark spec and complete GitHub-Flavored Markup spec, making it the most complete markdown library for PHP.
$parser = new \League\CommonMark\CommonMarkConverter();
echo $parser->convertToHtml('# Hello World!');
// "<h1>Hello World!</h1>"CommonMark library consists of a parser that converts raw Markdown text to an Abstract-Syntax-Tree, and a render (HTML) that converts the AST to HTML. These components can be swapped to adapt to the needs, or its plugin support allows higher level modifications to the parser and renderer.
league/commonmark library also brings a command-line tool provides a fluent CLI interface to convert Markdown text.
PHP Markdown
PHP Markdown is a project created back in 2007, and actively maintained to this day. It was created by Michel Fortin, and has over 3,200 GitHub stars, and has over 26 million reports downloads on Packagist to date.
PHP Markdown is a port of the original Markdown parser written in Perl (by John Gruber), with improvements added later on.
PHP Markdown follows an architecture similar to Parsedown, as it offers a single PHP class that contains everything.
echo \Michelf\Markdown::defaultTransform('# Hello World!');
// "<h1>Hello World!</h1>"PHP Markdown also offers a Markdown Extra PHP class (Michelf\MarkdownExtra) that extends the main Michelf\Markdown class. Extending PHP Markdown is also done by simply extending either Markdown or MarkdownExtra classes.
PHP Markdown class exposes some public properties to configure the parsing and rendering behavior. It may be not intuitive to use it with a shared instance, for example with a Dependency Injection Container, if the configuration needs to be adjusted in different contexts. For simple uses cases, it provides a good balance of customization from this contained package.
Neither GitHub-Flavored Markup spec, nor CommonMark spec is implemented in full, but it provides widely used features.
cebe/markdown
cebe/markdown is a Markdown library created by Carsten Brandt. It is fast and extensible, and may be more user-friendly because its approach depends on parsing strings instead of complicated regular expressions used in projects such as PHP Markdown.
cebe/markdown has over 9,000 GitHub stars, over 12 million downloads reported on Packagist, and is used by over 100 dependents including Yii 2.
$parser = new \cebe\markdown\Markdown();
echo $parser->parse('# Hello World!');
// "<h1>Hello World!</h1>"Similar to CommonMark, cebe/markdown library also provides a command-line tool that may be helpful if the system cannot use tools such as cmark.
One of the most important differences with the way cebe/markdown library stands out is that it offers a more different approach for extending the syntax.
New line-level syntax features are added by declaring identify*, consume*, and render* methods in a child class, and the markdown class automatically calls all identify* methods for each line and are given opportunity to claim a syntax it consumes and renders.
In-line syntax features (e.g. highlighted <mark> tags) can be added with methods conforming to parse* pattern, and the markers declared in a DocBlock @marker tag.
It is also possible to create a whole new markdown flavor with minimal custom coding, and using the naming patterns the library offers.
Note that when using
cebe/markdownwith Opcache, theopcache.save_commentsconfiguration value must remain the default1. If it is set to0, Opcache will remove the DocBlock comments, making it impossible for this library to access the@markerDocBlock tags.
Most Popular Markdown Library
The number of GitHub stars a project has is quite often not a good measure for the quality or completeness of a project. However, stargazer count and number of downloads show the popularity of a project.
Parsedown is easily the most starred and most downloaded Markdown library with over a whopping 70 million downloads, and 13,000 stars to date.
Its popularity is well-deserved, because it is also the fastest Markdown processor!
Feature Comparison
Basic Syntax
| Parsedown | CommonMark | PHP MarkDown | cebe/markdown | |
|---|---|---|---|---|
**bold**/_italic_ |
✔ | ✔ | ✔ | ✔ |
# Headings |
✔ | ✔ | ✔ | ✔ |
[Links](foo.com) |
✔ | ✔ | ✔ | ✔ |
 |
✔ | ✔ | ✔ | ✔ |
- lists |
✔ | ✔ | ✔ | ✔ |
> blockquotes |
✔ | ✔ | ✔ | ✔ |
--- Line |
✔ | ✔ | ✔ | ✔ |
~~strike-through~~ |
✔ | ✔ (Extension) | ✘ | ✘ |
Code Blocks
| Parsedown | CommonMark | PHP MarkDown | cebe/markdown | |
|---|---|---|---|---|
Inline code |
✔ | ✔ | ✔ | ✔ |
| Indented code blocks | ✔ | ✔ | ✔ | ✔ |
| Fenced code blocks | ✔ | ✔ | ✔ | ✔ |
Tables
| Parsedown | CommonMark | PHP MarkDown | cebe/markdown | |
|---|---|---|---|---|
| Basic tables | ✔ | ✔ (Extension) | ✔ (MarkdownExtra) |
✔ (MarkdownExtra) |
| Aligned tables | ✔ | ✔ (Extension) | ✔ (MarkdownExtra) |
✔ (MarkdownExtra) |
References
| Parsedown | CommonMark | PHP MarkDown | cebe/markdown | |
|---|---|---|---|---|
| Footnotes | ✔ (ParsedownExtra) |
✔ (Extension) | ✔ (MarkdownExtra) |
✘ |
| Definition Lists | ✔ (ParsedownExtra) |
✘ | ✔ (MarkdownExtra) |
✘ |
| Header Anchors | ✔ (ParsedownExtra) |
✔ (Extension) | ✔ (MarkdownExtra) |
✔ (MarkdownExtra) |
CommonMark supports several other extensions, and is the only Markdown library that implements 100% of the CommonMark spec.
CommonMark built-in extension list lists even more features, making it a quite feature-rich library.
Most Extensible Markdown Library
cebe/markdown, PHP MarkDown, and Parsedown all offer extending it, but it is not as versatile as CommonMark that provides a proper extension system.
With CommonMark, it is possible to use the several built-in extensions, or easily add new ones with provide parsing and rendering features without having to completely extend the Markdown class itself. Further, CommonMark has a modular architecture to easily create "environments" with arbitrary parsers and renders.
CommonMark is by far, the most extensible Markdown library in PHP.
Fastest Markdown Library
How fast a library can process a given text is an important measure. Given the differences in libraries (such as extensibility, feature set, etc.), it is important to note that the fastest library may not be the best one, because the faster ones may not be suitable for the use case, and depending on the size of the text, the difference may not be as pronounced either.
The following benchmark results are from PHP 8.0, using the average from one million iterations. This very post is used as the testing text as it contains basic formatting and tables, that is the lowest denominator for all four libraries.
| CommonMark | cebe/markdown | PHP MarkDown | Parsedown | |
|---|---|---|---|---|
| 0 bytes | 7.661 ms | 3.601 ms | 0.058 ms | 0.109 ms |
| 1.5 kb | 16.098 ms | 4.971 ms | 0.677 ms | 0.724 ms |
| 10 kb | 45.428 ms | 17.385 ms | 7.697 ms | 4.481 ms |
| 100 kb | 293.355 ms | 123.412 ms | 72.246 ms | 35.367 ms |
| 500 kb | 1,370.996 ms | 609.848 ms | 370.586 ms | 169.974 ms |
| 1,000 kb | 2,896.651 ms | 1,380.247 ms | 867.377 ms | 367.227 ms |
From the results, Parsedown holds quite well even with a 1 MB raw text input. Meanwhile, CommonMark is struggling to keep up with bigger text, and the trend line shows it will get slower with bigger texts.
Parsedown is the fastest Markdown library for PHP.
With all PHP Markdown processors compared, Parsedown is the fastest Markdown library, but it does not provide the extensibility and spec compatibility as CommonMark does.
CommonMark on the other hand, is an extensible, modular, and a more complete Markdown library that has a modern code base. It is the slowest of the bunch, especially for text over 100 KB, but for smaller blog-post size texts of 1-10 KB, its performance overhead may not be as significant.
