commonmark

Highly-extensible PHP Markdown parser which fully supports the CommonMark and GFM specs.

2,770

196

2,770

View on GitHub

Top Related Projects

php-markdown

3,432

Parser for Markdown and Markdown Extra derived from the original Markdown.pl by John Gruber.

markdown

1,002

A super fast, highly extensible markdown parser for PHP

html5-php

1,614

An HTML5 parser and serializer for PHP.

Quick Overview

The PHP League's CommonMark is a highly extensible PHP Markdown parser which fully supports the CommonMark and GitHub Flavored Markdown specifications. It provides a robust, flexible, and efficient way to convert Markdown to HTML in PHP applications.

Pros

Fully compliant with CommonMark and GitHub Flavored Markdown specs
Highly extensible with a plugin system for custom syntax and renderers
Excellent performance and memory efficiency
Well-documented with comprehensive guides and examples

Cons

Learning curve for advanced customizations and extensions
May be overkill for simple Markdown parsing needs
Requires PHP 7.4 or higher, which might not be available on older systems
Some features require additional extensions or plugins

Code Examples

Basic Markdown to HTML conversion:

use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter();
echo $converter->convert('# Hello, world!');

Using GitHub Flavored Markdown:

use League\CommonMark\GithubFlavoredMarkdownConverter;

$converter = new GithubFlavoredMarkdownConverter();
echo $converter->convert('```php
echo "Hello, world!";
```');

Custom configuration:

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\Table\TableExtension;
use League\CommonMark\MarkdownConverter;

$environment = new Environment([
    'allow_unsafe_links' => false,
]);
$environment->addExtension(new CommonMarkCoreExtension());
$environment->addExtension(new TableExtension());

$converter = new MarkdownConverter($environment);
echo $converter->convert('| Column 1 | Column 2 |
|----------|----------|
| Row 1    | Row 1    |');

Getting Started

To get started with CommonMark, install it via Composer:

composer require league/commonmark

Then, use it in your PHP code:

require 'vendor/autoload.php';

use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter();
echo $converter->convert('# Hello, world!');

This will output:

<h1>Hello, world!</h1>

Competitor Comparisons

php-markdown

3,432

Parser for Markdown and Markdown Extra derived from the original Markdown.pl by John Gruber.

Pros of php-markdown

Simpler and more lightweight implementation
Easier to integrate into existing projects
Faster parsing for basic Markdown syntax

Cons of php-markdown

Less extensible and customizable
Fewer features and less support for advanced Markdown extensions
Less active development and community support

Code Comparison

php-markdown:

$parser = new Michelf\Markdown();
$html = $parser->transform($markdown);

commonmark:

$converter = new CommonMarkConverter();
$html = $converter->convert($markdown);

Both libraries offer straightforward usage, but commonmark provides more options for configuration and customization:

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

commonmark also supports easy extension integration:

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\Table\TableExtension;

$environment = new Environment();
$environment->addExtension(new CommonMarkCoreExtension());
$environment->addExtension(new TableExtension());
$converter = new MarkdownConverter($environment);

While php-markdown is simpler and faster for basic Markdown parsing, commonmark offers more flexibility, features, and extensibility, making it a better choice for projects requiring advanced Markdown capabilities or customization.

parsedown

14,825

Better Markdown Parser in PHP

Pros of Parsedown

Simpler and more lightweight, with fewer dependencies
Generally faster parsing speed for basic Markdown
Easier to set up and use for simple projects

Cons of Parsedown

Less extensible and customizable
Limited support for advanced Markdown features and extensions
Less active development and community support

Code Comparison

Parsedown:

$parsedown = new Parsedown();
$html = $parsedown->text('# Hello, world!');

CommonMark:

use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter();
$html = $converter->convert('# Hello, world!');

Key Differences

Parsedown is more focused on simplicity and speed for basic Markdown parsing
CommonMark offers a more robust and extensible architecture
CommonMark adheres more strictly to the CommonMark specification
Parsedown has a smaller footprint and fewer dependencies
CommonMark provides better support for advanced Markdown features and custom extensions

Use Cases

Parsedown

Simple blog or content management systems
Projects with basic Markdown needs
Applications where performance is a top priority

CommonMark

Complex documentation systems
Projects requiring advanced Markdown features
Applications needing customizable parsing behavior

markdown

1,002

A super fast, highly extensible markdown parser for PHP

Pros of markdown

Lightweight and fast performance
Simple API with easy integration
Supports GitHub Flavored Markdown (GFM)

Cons of markdown

Less extensive feature set compared to commonmark
Fewer customization options
Less active development and community support

Code Comparison

markdown:

$parser = new \cebe\markdown\Markdown();
$html = $parser->parse($markdown);

commonmark:

$converter = new CommonMarkConverter();
$html = $converter->convert($markdown);

Both libraries offer straightforward parsing of Markdown to HTML, but commonmark provides more advanced configuration options and extensibility.

markdown is a good choice for projects requiring a simple, lightweight Markdown parser with basic GFM support. It's easy to integrate and performs well.

commonmark offers a more robust solution with extensive customization options, active development, and a larger ecosystem of extensions. It's better suited for projects needing advanced Markdown features or specific parsing requirements.

Consider your project's needs, performance requirements, and desired feature set when choosing between these libraries. If simplicity and speed are priorities, markdown might be the better choice. For more complex Markdown processing needs, commonmark is likely the more suitable option.

html5-php

1,614

An HTML5 parser and serializer for PHP.

Pros of html5-php

Specialized in HTML5 parsing and serialization
Supports DOM manipulation and traversal
Includes HTML5 entity support

Cons of html5-php

Less actively maintained (last release in 2021)
Limited to HTML5 processing, not a general-purpose markup library
Larger codebase, potentially higher memory footprint

Code Comparison

html5-php:

$html = <<< EOT
  <html><body>
    <p>Hello, <b>World!</b></p>
  </body></html>
EOT;

$dom = HTML5::loadHTML($html);
$p = $dom->getElementsByTagName('p')->item(0);
echo $p->textContent; // Outputs: Hello, World!

commonmark:

use League\CommonMark\CommonMarkConverter;

$markdown = '# Hello, **World!**';
$converter = new CommonMarkConverter();
echo $converter->convert($markdown);
// Outputs: <h1>Hello, <strong>World!</strong></h1>

Summary

html5-php is focused on HTML5 parsing and manipulation, making it suitable for projects requiring detailed HTML processing. commonmark, on the other hand, is a Markdown parser and renderer, offering a different set of features for working with lightweight markup. The choice between them depends on whether you need HTML5 specific functionality or Markdown processing capabilities.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

league/commonmark

league/commonmark is a highly-extensible PHP Markdown parser created by Colin O'Dell which supports the full CommonMark spec and GitHub-Flavored Markdown. It is based on the CommonMark JS reference implementation by John MacFarlane (@jgm).

ð¦ Installation & Basic Usage

This project requires PHP 7.4 or higher with the mbstring extension. To install it via Composer simply run:

$ composer require league/commonmark

The 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->convert('# Hello World!');

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

Or if you want GitHub-Flavored Markdown, use the GithubFlavoredMarkdownConverter class instead:

use League\CommonMark\GithubFlavoredMarkdownConverter;

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

echo $converter->convert('# 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.

[!CAUTION] 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, consider using a library (like HTML Purifier) to provide additional HTML filtering.

ð Documentation

Full documentation on advanced usage, configuration, and customization can be found at commonmark.thephpleague.com.

â« Upgrading

Information on how to upgrade to newer versions of this library can be found at https://commonmark.thephpleague.com/releases.

ð» GitHub-Flavored Markdown

The GithubFlavoredMarkdownConverter shown earlier is a drop-in replacement for the CommonMarkConverter which adds additional features found in the GFM spec:

Autolinks
Disallowed raw HTML
Strikethrough
Tables
Task Lists

See the Extensions documentation for more details on how to include only certain GFM features if you don't want them all.

ðï¸ Related Packages

Integrations

Included Extensions

See our extension documentation for a full list of extensions bundled with this library.

Community Extensions

Custom parsers/renderers can be bundled into extensions which extend CommonMark. Here are some that you may find interesting:

Emoji extension - UTF-8 emoji extension with Github tag.
Sup Sub extensions - Adds support of superscript and subscript (<sup> and <sub> HTML tags)
YouTube iframe extension - Replaces youtube link with iframe.
Lazy Image extension - Adds various options for lazy loading of images.
Marker Extension - Adds support of highlighted text (<mark> HTML tag)

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!

Others

Check out the other cool things people are doing with league/commonmark: https://packagist.org/packages/league/commonmark/dependents

ð·ï¸ Versioning

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.

ð ï¸ Maintenance & Support

When a new minor version (e.g. 2.0 -> 2.1) is released, the previous one (2.0) will continue to receive security and critical bug fixes for at least 3 months.

When a new major version is released (e.g. 1.6 -> 2.0), the previous one (1.6) will receive critical 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.

ð·ââï¸ Contributing

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.

ð§ª Testing

$ composer test

This will also test league/commonmark against the latest supported spec.

ð Performance Benchmarks

You can compare the performance of league/commonmark to other popular parsers by running the included benchmark tool:

$ ./tests/benchmark/benchmark.php

ð¥ Credits & Acknowledgements

This code was originally 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.

And a huge thanks to all of our amazing contributors:

ð License

league/commonmark is licensed under the BSD-3 license. See the LICENSE file for more details.

ðï¸ Governance

This project is primarily maintained by Colin O'Dell. Members of the PHP League Leadership Team may occasionally assist with some of these duties.

ðºï¸ Who Uses It?

This project is used by Drupal, Laravel Framework, Cachet, Firefly III, Neos, Daux.io, and more!

Get professional support for league/commonmark with a Tidelift subscription
_{Tidelift helps make open source sustainable for maintainers while giving companies
assurances about security, maintenance, and licensing for their dependencies.}

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of php-markdown

Cons of php-markdown

Code Comparison

Pros of Parsedown

Cons of Parsedown

Code Comparison

Key Differences

Use Cases

Parsedown

CommonMark

Pros of markdown

Cons of markdown

Code Comparison

Pros of html5-php

Cons of html5-php

Code Comparison

Summary

Convert designs to code with AI

README

league/commonmark

ð¦ Installation & Basic Usage

ð Documentation

â« Upgrading

ð» GitHub-Flavored Markdown

ðï¸ Related Packages

Integrations

Included Extensions

Community Extensions

Others

ð·ï¸ Versioning

ð ï¸ Maintenance & Support

ð·ââï¸ Contributing

ð§ª Testing

ð Performance Benchmarks

ð¥ Credits & Acknowledgements

Sponsors

ð License

ðï¸ Governance

ðºï¸ Who Uses It?

Top Related Projects

Convert designs to code with AI

ð¦ Installation & Basic Usage

ð Documentation

â« Upgrading

ð» GitHub-Flavored Markdown

ðï¸ Related Packages

ð·ï¸ Versioning

ð ï¸ Maintenance & Support

ð·ââï¸ Contributing

ð§ª Testing

ð Performance Benchmarks

ð¥ Credits & Acknowledgements

ð License

ðï¸ Governance

ðºï¸ Who Uses It?