13.08 KB
<h1>league/commonmark</h1>
<p><a href="https://gitter.im/thephpleague/commonmark?utm_source=badge&amp;utm_medium=badge&amp;utm_campaign=pr-badge&amp;utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Join the chat at https://gitter.im/thephpleague/commonmark" /></a></p>
<p><a href="https://packagist.org/packages/league/commonmark"><img src="https://img.shields.io/packagist/v/league/commonmark.svg?style=flat-square" alt="Latest Version" /></a>
<a href="https://packagist.org/packages/league/commonmark"><img src="https://img.shields.io/packagist/dt/league/commonmark.svg?style=flat-square" alt="Total Downloads" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-BSD--3-brightgreen.svg?style=flat-square" alt="Software License" /></a>
<a href="https://travis-ci.org/thephpleague/commonmark"><img src="https://img.shields.io/travis/thephpleague/commonmark/master.svg?style=flat-square" alt="Build Status" /></a>
<a href="https://scrutinizer-ci.com/g/thephpleague/commonmark/code-structure"><img src="https://img.shields.io/scrutinizer/coverage/g/thephpleague/commonmark.svg?style=flat-square" alt="Coverage Status" /></a>
<a href="https://scrutinizer-ci.com/g/thephpleague/commonmark"><img src="https://img.shields.io/scrutinizer/g/thephpleague/commonmark.svg?style=flat-square" alt="Quality Score" /></a>
<a href="https://insight.sensiolabs.com/projects/9bf971c0-458f-4a19-9898-127728dbd65d"><img src="https://img.shields.io/sensiolabs/i/9bf971c0-458f-4a19-9898-127728dbd65d.svg?style=flat-square" alt="SensioLabs Insight" /></a>
<a href="https://bestpractices.coreinfrastructure.org/projects/126"><img src="https://bestpractices.coreinfrastructure.org/projects/126/badge" alt="CII Best Practices" /></a></p>
<p><strong>league/commonmark</strong> is a PHP-based Markdown parser created by <a href="https://www.twitter.com/colinodell">Colin O'Dell</a> which supports the full <a href="http://commonmark.org/">CommonMark</a> spec.  It is based on the <a href="https://github.com/jgm/commonmark.js">CommonMark JS reference implementation</a> by <a href="http://johnmacfarlane.net">John MacFarlane</a> (<a href="https://github.com/jgm">@jgm</a>).</p>
<h2>Goals</h2>
<ul>
<li>Fully support the CommonMark spec (100% compliance)</li>
<li>Match the C and JavaScript implementations of CommonMark to make a logical and similar API</li>
<li>Continuously improve performance without sacrificing quality or compliance</li>
<li>Provide an extensible parser/renderer which users may customize as needed</li>
</ul>
<h2>Installation</h2>
<p>This project can be installed via <a href="https://getcomposer.org/">Composer</a>:</p>
<pre><code class="language-bash">$ composer require league/commonmark
</code></pre>
<p><strong>Note:</strong> See <a href="#versioning">Versioning</a> for important information on which version constraints you should use.</p>
<h2>Basic Usage</h2>
<p>The <code>CommonMarkConverter</code> class provides a simple wrapper for converting CommonMark to HTML:</p>
<pre><code class="language-php">use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter();
echo $converter-&gt;convertToHtml('# Hello World!');

// &lt;h1&gt;Hello World!&lt;/h1&gt;
</code></pre>
<p>:warning: <strong>Security warning:</strong> If you will be parsing untrusted input from users, please consider setting the <code>html_input</code> and <code>allow_unsafe_links</code> options. See <a href="https://commonmark.thephpleague.com/security/">https://commonmark.thephpleague.com/security/</a> for more details.</p>
<h2>Advanced Usage &amp; Customization</h2>
<p>The actual conversion process requires two steps:</p>
<ol>
<li>Parsing the Markdown input into an AST</li>
<li>Rendering the AST document as HTML</li>
</ol>
<p>Although the <code>CommonMarkConverter</code> wrapper simplifies this process for you, advanced users will likely want to do this themselves:</p>
<pre><code class="language-php">use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;

// Obtain a pre-configured Environment with all the CommonMark parsers/renderers ready-to-go
$environment = Environment::createCommonMarkEnvironment();

// Optional: Add your own parsers, renderers, extensions, etc. (if desired)
// For example:  $environment-&gt;addInlineParser(new TwitterHandleParser());

// Define your configuration:
$config = ['html_input' =&gt; 'escape'];

// Create the converter
$converter = new CommonMarkConverter($config, $environment);

// Here's our sample input
$markdown = '# Hello World!';

// Let's render it!
echo $converter-&gt;convertToHtml($markdown);

// The output should be:
// &lt;h1&gt;Hello World!&lt;/h1&gt;
</code></pre>
<p>This approach allows you to access/modify the AST before rendering it.</p>
<p>You can also add custom parsers/renderers by <a href="https://commonmark.thephpleague.com/customization/environment/">registering them with the <code>Environment</code> class</a>.
The <a href="https://commonmark.thephpleague.com/">documentation</a> provides several <a href="https://commonmark.thephpleague.com/customization/overview/#examples">customization examples</a> such as:</p>
<ul>
<li><a href="https://commonmark.thephpleague.com/customization/inline-parsing#example-1---twitter-handles">Parsing Twitter handles into profile links</a></li>
<li><a href="https://commonmark.thephpleague.com/customization/inline-parsing#example-2---emoticons">Converting smilies into emoticon images</a></li>
</ul>
<p>You can also reference the core CommonMark parsers/renderers as they use the same functionality available to you.</p>
<h2>Documentation</h2>
<p>Documentation can be found at <a href="https://commonmark.thephpleague.com/">commonmark.thephpleague.com</a>.</p>
<h2>Related Packages</h2>
<h3>Integrations</h3>
<ul>
<li><a href="https://github.com/gourmet/common-mark">CakePHP 3</a></li>
<li><a href="https://www.drupal.org/project/markdown">Drupal 7 &amp; 8</a></li>
<li><a href="https://github.com/GrahamCampbell/Laravel-Markdown">Laravel 4 &amp; 5</a></li>
<li><a href="https://github.com/bcremer/sculpin-commonmark-bundle">Sculpin</a></li>
<li><a href="https://github.com/webuni/commonmark-bundle">Symfony</a></li>
<li><a href="https://github.com/webuni/commonmark-twig-renderer">Twig</a></li>
</ul>
<h3>CommonMark Extras</h3>
<p>You can find several examples of useful extensions and customizations in the <a href="https://github.com/thephpleague/commonmark-extras">league/commonmark-extras package</a>.  You can add them to your parser or use them as examples to <a href="https://commonmark.thephpleague.com/customization/overview/">develop your own custom features</a>.</p>
<h3>Community Extensions</h3>
<p>Custom parsers/renderers can be bundled into extensions which extend CommonMark.  Here are some that you may find interesting:</p>
<ul>
<li><a href="https://github.com/dshafik/markua">Markua</a> - Markdown parser for PHP which intends to support the full Markua spec.</li>
<li><a href="https://github.com/webuni/commonmark-table-extension">CommonMark Table Extension</a> - Adds the ability to create tables in CommonMark documents.</li>
<li><a href="https://github.com/webuni/commonmark-attributes-extension">CommonMark Attributes Extension</a> - Adds a syntax to define attributes on the various HTML elements.</li>
<li><a href="https://github.com/AltThree/Emoji">Alt Three Emoji</a> An emoji parser for CommonMark.</li>
<li><a href="https://github.com/uafrica/commonmark-ext">uafrica/commonmark-ext</a> - Adds strikethrough support.</li>
<li><a href="https://github.com/OWS/commonmark-sup-sub-extensions">Sup Sub extensions</a> - Adds support of superscript and subscript (<code>&lt;sup&gt;</code> and <code>&lt;sub&gt;</code> HTML tags)</li>
</ul>
<p>If you build your own, feel free to submit a PR to add it to this list!</p>
<h3>Others</h3>
<p>Check out the other cool things people are doing with <code>league/commonmark</code>: <a href="https://packagist.org/packages/league/commonmark/dependents">https://packagist.org/packages/league/commonmark/dependents</a></p>
<h2>Compatibility with CommonMark</h2>
<p>This project aims to fully support the entire <a href="http://spec.commonmark.org/">CommonMark spec</a>. Other flavors of Markdown may work but are not supported.  Any/all changes made to the <a href="http://spec.commonmark.org/">spec</a> or <a href="https://github.com/jgm/commonmark.js">JS reference implementation</a> should eventually find their way back into this codebase.</p>
<p>league/commonmark 0.15.5 and higher supports version 0.28 of the <a href="http://spec.commonmark.org/">CommonMark spec</a>.</p>
<p>(This package is <strong>not</strong> part of CommonMark, but rather a compatible derivative.)</p>
<h2>Testing</h2>
<pre><code class="language-bash">$ ./vendor/bin/phpunit
</code></pre>
<p>This will also test league/commonmark against the latest supported spec.</p>
<h2>Performance Benchmarks</h2>
<p>You can compare the performance of <strong>league/commonmark</strong> to other popular parsers by running the included benchmark tool:</p>
<pre><code class="language-bash">$ ./tests/benchmark/benchmark.php
</code></pre>
<h2>Versioning</h2>
<p><a href="http://semver.org/">SemVer</a> will be followed closely.  0.x.0 versions will introduce breaking changes to the codebase, so be careful which version constraints you use. <strong>It's highly recommended that you use <a href="https://getcomposer.org/doc/articles/versions.md#caret">Composer's caret operator</a> to ensure compatibility</strong>; for example: <code>^0.16</code>.  This is equivalent to <code>&gt;=0.16.0 &lt;0.17.0</code>.</p>
<p>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.</p>
<p>If you're only using the <code>CommonMarkConverter</code> class to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like <code>~0.16</code>, <code>&gt;0.16</code>, etc.  I personally promise to never break this specific class in any future 0.x release.</p>
<h2>Stability</h2>
<p>While this package does work well, the underlying code should not be considered &quot;stable&quot; 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 <code>@api</code> are not expected to change, but other methods/classes might.</p>
<p>Major release 1.0.0 will be reserved for when both CommonMark and this project are considered stable (see <a href="http://talk.commonmark.org/t/issues-to-resolve-before-1-0-release/1287">outstanding CommonMark spec issues</a>).  0.x.y will be used until that happens.</p>
<h2>Contributing</h2>
<p>If you encounter a bug in the spec, please report it to the <a href="http://commonmark.org/">CommonMark</a> project.  Any resulting fix will eventually be implemented in this project as well.</p>
<p>For now, I'd like to maintain similar logic as the <a href="https://github.com/jgm/commonmark.js">JS reference implementation</a> until everything is stable.  I'll gladly accept any contributions which:</p>
<ul>
<li>Mirror fixes made to the <a href="https://github.com/jgm/commonmark.js">reference implementation</a></li>
<li>Optimize existing methods or regular expressions</li>
<li>Fix issues with adhering to the spec examples</li>
</ul>
<p>Major refactoring should be avoided for now so that we can easily follow updates made to <a href="https://github.com/jgm/commonmark.js">the reference implementation</a>.  This restriction will likely be lifted once the CommonMark specs and implementations are considered stable.</p>
<p>Please see <a href="https://github.com/thephpleague/commonmark/blob/master/CONTRIBUTING.md">CONTRIBUTING</a> for additional details.</p>
<h2>Security</h2>
<p>If you discover any security related issues, please email your report privately to [email protected] instead of using the issue tracker.</p>
<h2>Credits &amp; Acknowledgements</h2>
<ul>
<li><a href="https://www.twitter.com/colinodell">Colin O'Dell</a></li>
<li><a href="https://github.com/jgm">John MacFarlane</a></li>
<li><a href="https://github.com/thephpleague/commonmark/contributors">All Contributors</a></li>
</ul>
<p>This code is a port of the <a href="https://github.com/jgm/commonmark.js">CommonMark JS reference implementation</a> which is written, maintained and copyrighted by <a href="http://johnmacfarlane.net">John MacFarlane</a>.  This project simply wouldn't exist without his work.</p>
<p>Also a huge thank you to <a href="https://www.jetbrains.com/">JetBrains</a> for supporting the development of this project with complimentary <a href="https://www.jetbrains.com/phpstorm/">PhpStorm</a> licenses.</p>
<h2>License</h2>
<p><strong>league/commonmark</strong> is licensed under the BSD-3 license.  See the <code>LICENSE</code> file for more details.</p>
<h2>Governance</h2>
<p>This project is primarily maintained by <a href="https://www.twitter.com/colinodell">Colin O'Dell</a>.  Members of the <a href="https://thephpleague.com">PHP League</a> Leadership Team may occasionally assist with some of these duties.</p>

league/commonmark

Join the chat at https://gitter.im/thephpleague/commonmark

Latest Version Total Downloads Software License Build Status Coverage Status Quality Score SensioLabs Insight CII Best Practices

league/commonmark is a PHP-based 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).

Goals

  • Fully support the CommonMark spec (100% compliance)
  • Match the C and JavaScript implementations of CommonMark to make a logical and similar API
  • Continuously improve performance without sacrificing quality or compliance
  • Provide an extensible parser/renderer which users may customize as needed

Installation

This project can be installed via Composer:

$ composer require league/commonmark

Note: See Versioning for important information on which version constraints you should use.

Basic Usage

The 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>

:warning: Security warning: If you will be parsing untrusted input from users, please consider setting the html_input and allow_unsafe_links options. See https://commonmark.thephpleague.com/security/ for more details.

Advanced Usage & Customization

The actual conversion process requires two steps:

  1. Parsing the Markdown input into an AST
  2. Rendering the AST document as HTML

Although the CommonMarkConverter wrapper simplifies this process for you, advanced users will likely want to do this themselves:

use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;

// Obtain a pre-configured Environment with all the CommonMark parsers/renderers ready-to-go
$environment = Environment::createCommonMarkEnvironment();

// Optional: Add your own parsers, renderers, extensions, etc. (if desired)
// For example:  $environment->addInlineParser(new TwitterHandleParser());

// Define your configuration:
$config = ['html_input' => 'escape'];

// Create the converter
$converter = new CommonMarkConverter($config, $environment);

// Here's our sample input
$markdown = '# Hello World!';

// Let's render it!
echo $converter->convertToHtml($markdown);

// The output should be:
// <h1>Hello World!</h1>

This approach allows you to access/modify the AST before rendering it.

You can also add custom parsers/renderers by registering them with the Environment class. The documentation provides several customization examples such as:

You can also reference the core CommonMark parsers/renderers as they use the same functionality available to you.

Documentation

Documentation can be found at commonmark.thephpleague.com.

Related Packages

Integrations

CommonMark Extras

You can find several examples of useful extensions and customizations in the league/commonmark-extras package. You can add them to your parser or use them as examples to develop your own custom features.

Community Extensions

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

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

Compatibility with CommonMark

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.15.5 and higher supports version 0.28 of the CommonMark spec.

(This package is not part of CommonMark, but rather a compatible derivative.)

Testing

$ ./vendor/bin/phpunit

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

Versioning

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.16. This is equivalent to >=0.16.0 <0.17.0.

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 to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like ~0.16, >0.16, etc. I personally promise to never break this specific class in any future 0.x release.

Stability

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 both CommonMark and this project are considered stable (see outstanding CommonMark spec issues). 0.x.y will be used until that happens.

Contributing

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.

Security

If you discover any security related issues, please email your report privately to [email protected] instead of using the issue tracker.

Credits & Acknowledgements

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.

Also a huge thank you to JetBrains for supporting the development of this project with complimentary PhpStorm licenses.

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.

<h1>league/commonmark</h1>
<p><a href="https://gitter.im/thephpleague/commonmark?utm_source=badge&amp;utm_medium=badge&amp;utm_campaign=pr-badge&amp;utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Join the chat at https://gitter.im/thephpleague/commonmark" /></a></p>
<p><a href="https://packagist.org/packages/league/commonmark"><img src="https://img.shields.io/packagist/v/league/commonmark.svg?style=flat-square" alt="Latest Version" /></a>
<a href="https://packagist.org/packages/league/commonmark"><img src="https://img.shields.io/packagist/dt/league/commonmark.svg?style=flat-square" alt="Total Downloads" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-BSD--3-brightgreen.svg?style=flat-square" alt="Software License" /></a>
<a href="https://travis-ci.org/thephpleague/commonmark"><img src="https://img.shields.io/travis/thephpleague/commonmark/master.svg?style=flat-square" alt="Build Status" /></a>
<a href="https://scrutinizer-ci.com/g/thephpleague/commonmark/code-structure"><img src="https://img.shields.io/scrutinizer/coverage/g/thephpleague/commonmark.svg?style=flat-square" alt="Coverage Status" /></a>
<a href="https://scrutinizer-ci.com/g/thephpleague/commonmark"><img src="https://img.shields.io/scrutinizer/g/thephpleague/commonmark.svg?style=flat-square" alt="Quality Score" /></a>
<a href="https://insight.sensiolabs.com/projects/9bf971c0-458f-4a19-9898-127728dbd65d"><img src="https://img.shields.io/sensiolabs/i/9bf971c0-458f-4a19-9898-127728dbd65d.svg?style=flat-square" alt="SensioLabs Insight" /></a>
<a href="https://bestpractices.coreinfrastructure.org/projects/126"><img src="https://bestpractices.coreinfrastructure.org/projects/126/badge" alt="CII Best Practices" /></a></p>
<p><strong>league/commonmark</strong> is a PHP-based Markdown parser created by <a href="https://www.twitter.com/colinodell">Colin O'Dell</a> which supports the full <a href="http://commonmark.org/">CommonMark</a> spec.  It is based on the <a href="https://github.com/jgm/commonmark.js">CommonMark JS reference implementation</a> by <a href="http://johnmacfarlane.net">John MacFarlane</a> (<a href="https://github.com/jgm">@jgm</a>).</p>
<h2>Goals</h2>
<ul>
<li>Fully support the CommonMark spec (100% compliance)</li>
<li>Match the C and JavaScript implementations of CommonMark to make a logical and similar API</li>
<li>Continuously improve performance without sacrificing quality or compliance</li>
<li>Provide an extensible parser/renderer which users may customize as needed</li>
</ul>
<h2>Installation</h2>
<p>This project can be installed via <a href="https://getcomposer.org/">Composer</a>:</p>
<pre><code class="language-bash">$ composer require league/commonmark
</code></pre>
<p><strong>Note:</strong> See <a href="#versioning">Versioning</a> for important information on which version constraints you should use.</p>
<h2>Basic Usage</h2>
<p>The <code>CommonMarkConverter</code> class provides a simple wrapper for converting CommonMark to HTML:</p>
<pre><code class="language-php">use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter();
echo $converter-&gt;convertToHtml('# Hello World!');

// &lt;h1&gt;Hello World!&lt;/h1&gt;
</code></pre>
<p>:warning: <strong>Security warning:</strong> If you will be parsing untrusted input from users, please consider setting the <code>html_input</code> and <code>allow_unsafe_links</code> options. See <a href="https://commonmark.thephpleague.com/security/">https://commonmark.thephpleague.com/security/</a> for more details.</p>
<h2>Advanced Usage &amp; Customization</h2>
<p>The actual conversion process requires two steps:</p>
<ol>
<li>Parsing the Markdown input into an AST</li>
<li>Rendering the AST document as HTML</li>
</ol>
<p>Although the <code>CommonMarkConverter</code> wrapper simplifies this process for you, advanced users will likely want to do this themselves:</p>
<pre><code class="language-php">use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;

// Obtain a pre-configured Environment with all the CommonMark parsers/renderers ready-to-go
$environment = Environment::createCommonMarkEnvironment();

// Optional: Add your own parsers, renderers, extensions, etc. (if desired)
// For example:  $environment-&gt;addInlineParser(new TwitterHandleParser());

// Define your configuration:
$config = ['html_input' =&gt; 'escape'];

// Create the converter
$converter = new CommonMarkConverter($config, $environment);

// Here's our sample input
$markdown = '# Hello World!';

// Let's render it!
echo $converter-&gt;convertToHtml($markdown);

// The output should be:
// &lt;h1&gt;Hello World!&lt;/h1&gt;
</code></pre>
<p>This approach allows you to access/modify the AST before rendering it.</p>
<p>You can also add custom parsers/renderers by <a href="https://commonmark.thephpleague.com/customization/environment/">registering them with the <code>Environment</code> class</a>.
The <a href="https://commonmark.thephpleague.com/">documentation</a> provides several <a href="https://commonmark.thephpleague.com/customization/overview/#examples">customization examples</a> such as:</p>
<ul>
<li>
<a href="https://commonmark.thephpleague.com/customization/inline-parsing#example-1---twitter-handles">Parsing Twitter handles into profile links</a>
</li>
<li>
<a href="https://commonmark.thephpleague.com/customization/inline-parsing#example-2---emoticons">Converting smilies into emoticon images</a>
</li>
</ul>
<p>You can also reference the core CommonMark parsers/renderers as they use the same functionality available to you.</p>
<h2>Documentation</h2>
<p>Documentation can be found at <a href="https://commonmark.thephpleague.com/">commonmark.thephpleague.com</a>.</p>
<h2>Related Packages</h2>
<h3>Integrations</h3>
<ul>
<li>
<a href="https://github.com/gourmet/common-mark">CakePHP 3</a>
</li>
<li>
<a href="https://www.drupal.org/project/markdown">Drupal 7 &amp; 8</a>
</li>
<li>
<a href="https://github.com/GrahamCampbell/Laravel-Markdown">Laravel 4 &amp; 5</a>
</li>
<li>
<a href="https://github.com/bcremer/sculpin-commonmark-bundle">Sculpin</a>
</li>
<li>
<a href="https://github.com/webuni/commonmark-bundle">Symfony</a>
</li>
<li>
<a href="https://github.com/webuni/commonmark-twig-renderer">Twig</a>
</li>
</ul>
<h3>CommonMark Extras</h3>
<p>You can find several examples of useful extensions and customizations in the <a href="https://github.com/thephpleague/commonmark-extras">league/commonmark-extras package</a>.  You can add them to your parser or use them as examples to <a href="https://commonmark.thephpleague.com/customization/overview/">develop your own custom features</a>.</p>
<h3>Community Extensions</h3>
<p>Custom parsers/renderers can be bundled into extensions which extend CommonMark.  Here are some that you may find interesting:</p>
<ul>
<li>
<a href="https://github.com/dshafik/markua">Markua</a> - Markdown parser for PHP which intends to support the full Markua spec.</li>
<li>
<a href="https://github.com/webuni/commonmark-table-extension">CommonMark Table Extension</a> - Adds the ability to create tables in CommonMark documents.</li>
<li>
<a href="https://github.com/webuni/commonmark-attributes-extension">CommonMark Attributes Extension</a> - Adds a syntax to define attributes on the various HTML elements.</li>
<li>
<a href="https://github.com/AltThree/Emoji">Alt Three Emoji</a> An emoji parser for CommonMark.</li>
<li>
<a href="https://github.com/uafrica/commonmark-ext">uafrica/commonmark-ext</a> - Adds strikethrough support.</li>
<li>
<a href="https://github.com/OWS/commonmark-sup-sub-extensions">Sup Sub extensions</a> - Adds support of superscript and subscript (<code>&lt;sup&gt;</code> and <code>&lt;sub&gt;</code> HTML tags)</li>
</ul>
<p>If you build your own, feel free to submit a PR to add it to this list!</p>
<h3>Others</h3>
<p>Check out the other cool things people are doing with <code>league/commonmark</code>: <a href="https://packagist.org/packages/league/commonmark/dependents">https://packagist.org/packages/league/commonmark/dependents</a></p>
<h2>Compatibility with CommonMark</h2>
<p>This project aims to fully support the entire <a href="http://spec.commonmark.org/">CommonMark spec</a>. Other flavors of Markdown may work but are not supported.  Any/all changes made to the <a href="http://spec.commonmark.org/">spec</a> or <a href="https://github.com/jgm/commonmark.js">JS reference implementation</a> should eventually find their way back into this codebase.</p>
<p>league/commonmark 0.15.5 and higher supports version 0.28 of the <a href="http://spec.commonmark.org/">CommonMark spec</a>.</p>
<p>(This package is <strong>not</strong> part of CommonMark, but rather a compatible derivative.)</p>
<h2>Testing</h2>
<pre><code class="language-bash">$ ./vendor/bin/phpunit
</code></pre>
<p>This will also test league/commonmark against the latest supported spec.</p>
<h2>Performance Benchmarks</h2>
<p>You can compare the performance of <strong>league/commonmark</strong> to other popular parsers by running the included benchmark tool:</p>
<pre><code class="language-bash">$ ./tests/benchmark/benchmark.php
</code></pre>
<h2>Versioning</h2>
<p><a href="http://semver.org/">SemVer</a> will be followed closely.  0.x.0 versions will introduce breaking changes to the codebase, so be careful which version constraints you use. <strong>It's highly recommended that you use <a href="https://getcomposer.org/doc/articles/versions.md#caret">Composer's caret operator</a> to ensure compatibility</strong>; for example: <code>^0.16</code>.  This is equivalent to <code>&gt;=0.16.0 &lt;0.17.0</code>.</p>
<p>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.</p>
<p>If you're only using the <code>CommonMarkConverter</code> class to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like <code>~0.16</code>, <code>&gt;0.16</code>, etc.  I personally promise to never break this specific class in any future 0.x release.</p>
<h2>Stability</h2>
<p>While this package does work well, the underlying code should not be considered &quot;stable&quot; 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 <code>@api</code> are not expected to change, but other methods/classes might.</p>
<p>Major release 1.0.0 will be reserved for when both CommonMark and this project are considered stable (see <a href="http://talk.commonmark.org/t/issues-to-resolve-before-1-0-release/1287">outstanding CommonMark spec issues</a>).  0.x.y will be used until that happens.</p>
<h2>Contributing</h2>
<p>If you encounter a bug in the spec, please report it to the <a href="http://commonmark.org/">CommonMark</a> project.  Any resulting fix will eventually be implemented in this project as well.</p>
<p>For now, I'd like to maintain similar logic as the <a href="https://github.com/jgm/commonmark.js">JS reference implementation</a> until everything is stable.  I'll gladly accept any contributions which:</p>
<ul>
<li>Mirror fixes made to the <a href="https://github.com/jgm/commonmark.js">reference implementation</a>
</li>
<li>Optimize existing methods or regular expressions</li>
<li>Fix issues with adhering to the spec examples</li>
</ul>
<p>Major refactoring should be avoided for now so that we can easily follow updates made to <a href="https://github.com/jgm/commonmark.js">the reference implementation</a>.  This restriction will likely be lifted once the CommonMark specs and implementations are considered stable.</p>
<p>Please see <a href="https://github.com/thephpleague/commonmark/blob/master/CONTRIBUTING.md">CONTRIBUTING</a> for additional details.</p>
<h2>Security</h2>
<p>If you discover any security related issues, please email your report privately to [email protected] instead of using the issue tracker.</p>
<h2>Credits &amp; Acknowledgements</h2>
<ul>
<li>
<a href="https://www.twitter.com/colinodell">Colin O'Dell</a>
</li>
<li>
<a href="https://github.com/jgm">John MacFarlane</a>
</li>
<li>
<a href="https://github.com/thephpleague/commonmark/contributors">All Contributors</a>
</li>
</ul>
<p>This code is a port of the <a href="https://github.com/jgm/commonmark.js">CommonMark JS reference implementation</a> which is written, maintained and copyrighted by <a href="http://johnmacfarlane.net">John MacFarlane</a>.  This project simply wouldn't exist without his work.</p>
<p>Also a huge thank you to <a href="https://www.jetbrains.com/">JetBrains</a> for supporting the development of this project with complimentary <a href="https://www.jetbrains.com/phpstorm/">PhpStorm</a> licenses.</p>
<h2>License</h2>
<p><strong>league/commonmark</strong> is licensed under the BSD-3 license.  See the <code>LICENSE</code> file for more details.</p>
<h2>Governance</h2>
<p>This project is primarily maintained by <a href="https://www.twitter.com/colinodell">Colin O'Dell</a>.  Members of the <a href="https://thephpleague.com">PHP League</a> Leadership Team may occasionally assist with some of these duties.</p>

league/commonmark

Join the chat at https://gitter.im/thephpleague/commonmark

Latest Version Total Downloads Software License Build Status Coverage Status Quality Score SensioLabs Insight CII Best Practices

league/commonmark is a PHP-based 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).

Goals

  • Fully support the CommonMark spec (100% compliance)
  • Match the C and JavaScript implementations of CommonMark to make a logical and similar API
  • Continuously improve performance without sacrificing quality or compliance
  • Provide an extensible parser/renderer which users may customize as needed

Installation

This project can be installed via Composer:

$ composer require league/commonmark

Note: See Versioning for important information on which version constraints you should use.

Basic Usage

The 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>

:warning: Security warning: If you will be parsing untrusted input from users, please consider setting the html_input and allow_unsafe_links options. See https://commonmark.thephpleague.com/security/ for more details.

Advanced Usage & Customization

The actual conversion process requires two steps:

  1. Parsing the Markdown input into an AST
  2. Rendering the AST document as HTML

Although the CommonMarkConverter wrapper simplifies this process for you, advanced users will likely want to do this themselves:

use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;

// Obtain a pre-configured Environment with all the CommonMark parsers/renderers ready-to-go
$environment = Environment::createCommonMarkEnvironment();

// Optional: Add your own parsers, renderers, extensions, etc. (if desired)
// For example:  $environment->addInlineParser(new TwitterHandleParser());

// Define your configuration:
$config = ['html_input' => 'escape'];

// Create the converter
$converter = new CommonMarkConverter($config, $environment);

// Here's our sample input
$markdown = '# Hello World!';

// Let's render it!
echo $converter->convertToHtml($markdown);

// The output should be:
// <h1>Hello World!</h1>

This approach allows you to access/modify the AST before rendering it.

You can also add custom parsers/renderers by registering them with the Environment class. The documentation provides several customization examples such as:

You can also reference the core CommonMark parsers/renderers as they use the same functionality available to you.

Documentation

Documentation can be found at commonmark.thephpleague.com.

Related Packages

Integrations

CommonMark Extras

You can find several examples of useful extensions and customizations in the league/commonmark-extras package. You can add them to your parser or use them as examples to develop your own custom features.

Community Extensions

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

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

Compatibility with CommonMark

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.15.5 and higher supports version 0.28 of the CommonMark spec.

(This package is not part of CommonMark, but rather a compatible derivative.)

Testing

$ ./vendor/bin/phpunit

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

Versioning

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.16. This is equivalent to >=0.16.0 <0.17.0.

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 to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like ~0.16, >0.16, etc. I personally promise to never break this specific class in any future 0.x release.

Stability

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 both CommonMark and this project are considered stable (see outstanding CommonMark spec issues). 0.x.y will be used until that happens.

Contributing

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.

Security

If you discover any security related issues, please email your report privately to [email protected] instead of using the issue tracker.

Credits & Acknowledgements

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.

Also a huge thank you to JetBrains for supporting the development of this project with complimentary PhpStorm licenses.

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.

<h1>league/commonmark</h1>
<p><a href="https://gitter.im/thephpleague/commonmark?utm_source=badge&amp;utm_medium=badge&amp;utm_campaign=pr-badge&amp;utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Join the chat at https://gitter.im/thephpleague/commonmark" /></a></p>
<p><a href="https://packagist.org/packages/league/commonmark"><img src="https://img.shields.io/packagist/v/league/commonmark.svg?style=flat-square" alt="Latest Version" /></a>
<a href="https://packagist.org/packages/league/commonmark"><img src="https://img.shields.io/packagist/dt/league/commonmark.svg?style=flat-square" alt="Total Downloads" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-BSD--3-brightgreen.svg?style=flat-square" alt="Software License" /></a>
<a href="https://travis-ci.org/thephpleague/commonmark"><img src="https://img.shields.io/travis/thephpleague/commonmark/master.svg?style=flat-square" alt="Build Status" /></a>
<a href="https://scrutinizer-ci.com/g/thephpleague/commonmark/code-structure"><img src="https://img.shields.io/scrutinizer/coverage/g/thephpleague/commonmark.svg?style=flat-square" alt="Coverage Status" /></a>
<a href="https://scrutinizer-ci.com/g/thephpleague/commonmark"><img src="https://img.shields.io/scrutinizer/g/thephpleague/commonmark.svg?style=flat-square" alt="Quality Score" /></a>
<a href="https://insight.sensiolabs.com/projects/9bf971c0-458f-4a19-9898-127728dbd65d"><img src="https://img.shields.io/sensiolabs/i/9bf971c0-458f-4a19-9898-127728dbd65d.svg?style=flat-square" alt="SensioLabs Insight" /></a>
<a href="https://bestpractices.coreinfrastructure.org/projects/126"><img src="https://bestpractices.coreinfrastructure.org/projects/126/badge" alt="CII Best Practices" /></a></p>
<p><strong>league/commonmark</strong> is a PHP-based Markdown parser created by <a href="https://www.twitter.com/colinodell">Colin O'Dell</a> which supports the full <a href="http://commonmark.org/">CommonMark</a> spec.  It is based on the <a href="https://github.com/jgm/commonmark.js">CommonMark JS reference implementation</a> by <a href="http://johnmacfarlane.net">John MacFarlane</a> (<a href="https://github.com/jgm">@jgm</a>).</p>
<h2>Goals</h2>
<ul>
<li>Fully support the CommonMark spec (100% compliance)</li>
<li>Match the C and JavaScript implementations of CommonMark to make a logical and similar API</li>
<li>Continuously improve performance without sacrificing quality or compliance</li>
<li>Provide an extensible parser/renderer which users may customize as needed</li>
</ul>
<h2>Installation</h2>
<p>This project can be installed via <a href="https://getcomposer.org/">Composer</a>:</p>
<pre><code class="language-bash">$ composer require league/commonmark</code></pre>
<p><strong>Note:</strong> See <a href="#versioning">Versioning</a> for important information on which version constraints you should use.</p>
<h2>Basic Usage</h2>
<p>The <code>CommonMarkConverter</code> class provides a simple wrapper for converting CommonMark to HTML:</p>
<pre><code class="language-php">use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter();
echo $converter-&gt;convertToHtml('# Hello World!');

// &lt;h1&gt;Hello World!&lt;/h1&gt;</code></pre>
<p>:warning: <strong>Security warning:</strong> If you will be parsing untrusted input from users, please consider setting the <code>html_input</code> and <code>allow_unsafe_links</code> options. See <a href="https://commonmark.thephpleague.com/security/">https://commonmark.thephpleague.com/security/</a> for more details.</p>
<h2>Advanced Usage &amp; Customization</h2>
<p>The actual conversion process requires two steps:</p>
<ol>
<li>Parsing the Markdown input into an AST</li>
<li>Rendering the AST document as HTML</li>
</ol>
<p>Although the <code>CommonMarkConverter</code> wrapper simplifies this process for you, advanced users will likely want to do this themselves:</p>
<pre><code class="language-php">use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;

// Obtain a pre-configured Environment with all the CommonMark parsers/renderers ready-to-go
$environment = Environment::createCommonMarkEnvironment();

// Optional: Add your own parsers, renderers, extensions, etc. (if desired)
// For example:  $environment-&gt;addInlineParser(new TwitterHandleParser());

// Define your configuration:
$config = ['html_input' =&gt; 'escape'];

// Create the converter
$converter = new CommonMarkConverter($config, $environment);

// Here's our sample input
$markdown = '# Hello World!';

// Let's render it!
echo $converter-&gt;convertToHtml($markdown);

// The output should be:
// &lt;h1&gt;Hello World!&lt;/h1&gt;</code></pre>
<p>This approach allows you to access/modify the AST before rendering it.</p>
<p>You can also add custom parsers/renderers by <a href="https://commonmark.thephpleague.com/customization/environment/">registering them with the <code>Environment</code> class</a>.
The <a href="https://commonmark.thephpleague.com/">documentation</a> provides several <a href="https://commonmark.thephpleague.com/customization/overview/#examples">customization examples</a> such as:</p>
<ul>
<li><a href="https://commonmark.thephpleague.com/customization/inline-parsing#example-1---twitter-handles">Parsing Twitter handles into profile links</a></li>
<li><a href="https://commonmark.thephpleague.com/customization/inline-parsing#example-2---emoticons">Converting smilies into emoticon images</a></li>
</ul>
<p>You can also reference the core CommonMark parsers/renderers as they use the same functionality available to you.</p>
<h2>Documentation</h2>
<p>Documentation can be found at <a href="https://commonmark.thephpleague.com/">commonmark.thephpleague.com</a>.</p>
<h2>Related Packages</h2>
<h3>Integrations</h3>
<ul>
<li><a href="https://github.com/gourmet/common-mark">CakePHP 3</a></li>
<li><a href="https://www.drupal.org/project/markdown">Drupal 7 &amp; 8</a></li>
<li><a href="https://github.com/GrahamCampbell/Laravel-Markdown">Laravel 4 &amp; 5</a></li>
<li><a href="https://github.com/bcremer/sculpin-commonmark-bundle">Sculpin</a></li>
<li><a href="https://github.com/webuni/commonmark-bundle">Symfony</a></li>
<li><a href="https://github.com/webuni/commonmark-twig-renderer">Twig</a></li>
</ul>
<h3>CommonMark Extras</h3>
<p>You can find several examples of useful extensions and customizations in the <a href="https://github.com/thephpleague/commonmark-extras">league/commonmark-extras package</a>.  You can add them to your parser or use them as examples to <a href="https://commonmark.thephpleague.com/customization/overview/">develop your own custom features</a>.</p>
<h3>Community Extensions</h3>
<p>Custom parsers/renderers can be bundled into extensions which extend CommonMark.  Here are some that you may find interesting:</p>
<ul>
<li><a href="https://github.com/dshafik/markua">Markua</a> - Markdown parser for PHP which intends to support the full Markua spec.</li>
<li><a href="https://github.com/webuni/commonmark-table-extension">CommonMark Table Extension</a> - Adds the ability to create tables in CommonMark documents.</li>
<li><a href="https://github.com/webuni/commonmark-attributes-extension">CommonMark Attributes Extension</a> - Adds a syntax to define attributes on the various HTML elements.</li>
<li><a href="https://github.com/AltThree/Emoji">Alt Three Emoji</a> An emoji parser for CommonMark.</li>
<li><a href="https://github.com/uafrica/commonmark-ext">uafrica/commonmark-ext</a> - Adds strikethrough support.</li>
<li><a href="https://github.com/OWS/commonmark-sup-sub-extensions">Sup Sub extensions</a> - Adds support of superscript and subscript (<code>&lt;sup&gt;</code> and <code>&lt;sub&gt;</code> HTML tags)</li>
</ul>
<p>If you build your own, feel free to submit a PR to add it to this list!</p>
<h3>Others</h3>
<p>Check out the other cool things people are doing with <code>league/commonmark</code>: <a href="https://packagist.org/packages/league/commonmark/dependents">https://packagist.org/packages/league/commonmark/dependents</a></p>
<h2>Compatibility with CommonMark</h2>
<p>This project aims to fully support the entire <a href="http://spec.commonmark.org/">CommonMark spec</a>. Other flavors of Markdown may work but are not supported.  Any/all changes made to the <a href="http://spec.commonmark.org/">spec</a> or <a href="https://github.com/jgm/commonmark.js">JS reference implementation</a> should eventually find their way back into this codebase.</p>
<p>league/commonmark 0.15.5 and higher supports version 0.28 of the <a href="http://spec.commonmark.org/">CommonMark spec</a>.</p>
<p>(This package is <strong>not</strong> part of CommonMark, but rather a compatible derivative.)</p>
<h2>Testing</h2>
<pre><code class="language-bash">$ ./vendor/bin/phpunit</code></pre>
<p>This will also test league/commonmark against the latest supported spec.</p>
<h2>Performance Benchmarks</h2>
<p>You can compare the performance of <strong>league/commonmark</strong> to other popular parsers by running the included benchmark tool:</p>
<pre><code class="language-bash">$ ./tests/benchmark/benchmark.php</code></pre>
<h2>Versioning</h2>
<p><a href="http://semver.org/">SemVer</a> will be followed closely.  0.x.0 versions will introduce breaking changes to the codebase, so be careful which version constraints you use. <strong>It's highly recommended that you use <a href="https://getcomposer.org/doc/articles/versions.md#caret">Composer's caret operator</a> to ensure compatibility</strong>; for example: <code>^0.16</code>.  This is equivalent to <code>&gt;=0.16.0 &lt;0.17.0</code>.</p>
<p>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.</p>
<p>If you're only using the <code>CommonMarkConverter</code> class to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like <code>~0.16</code>, <code>&gt;0.16</code>, etc.  I personally promise to never break this specific class in any future 0.x release.</p>
<h2>Stability</h2>
<p>While this package does work well, the underlying code should not be considered &quot;stable&quot; 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 <code>@api</code> are not expected to change, but other methods/classes might.</p>
<p>Major release 1.0.0 will be reserved for when both CommonMark and this project are considered stable (see <a href="http://talk.commonmark.org/t/issues-to-resolve-before-1-0-release/1287">outstanding CommonMark spec issues</a>).  0.x.y will be used until that happens.</p>
<h2>Contributing</h2>
<p>If you encounter a bug in the spec, please report it to the <a href="http://commonmark.org/">CommonMark</a> project.  Any resulting fix will eventually be implemented in this project as well.</p>
<p>For now, I'd like to maintain similar logic as the <a href="https://github.com/jgm/commonmark.js">JS reference implementation</a> until everything is stable.  I'll gladly accept any contributions which:</p>
<ul>
<li>Mirror fixes made to the <a href="https://github.com/jgm/commonmark.js">reference implementation</a></li>
<li>Optimize existing methods or regular expressions</li>
<li>Fix issues with adhering to the spec examples</li>
</ul>
<p>Major refactoring should be avoided for now so that we can easily follow updates made to <a href="https://github.com/jgm/commonmark.js">the reference implementation</a>.  This restriction will likely be lifted once the CommonMark specs and implementations are considered stable.</p>
<p>Please see <a href="https://github.com/thephpleague/commonmark/blob/master/CONTRIBUTING.md">CONTRIBUTING</a> for additional details.</p>
<h2>Security</h2>
<p>If you discover any security related issues, please email your report privately to [email protected] instead of using the issue tracker.</p>
<h2>Credits &amp; Acknowledgements</h2>
<ul>
<li><a href="https://www.twitter.com/colinodell">Colin O'Dell</a></li>
<li><a href="https://github.com/jgm">John MacFarlane</a></li>
<li><a href="https://github.com/thephpleague/commonmark/contributors">All Contributors</a></li>
</ul>
<p>This code is a port of the <a href="https://github.com/jgm/commonmark.js">CommonMark JS reference implementation</a> which is written, maintained and copyrighted by <a href="http://johnmacfarlane.net">John MacFarlane</a>.  This project simply wouldn't exist without his work.</p>
<p>Also a huge thank you to <a href="https://www.jetbrains.com/">JetBrains</a> for supporting the development of this project with complimentary <a href="https://www.jetbrains.com/phpstorm/">PhpStorm</a> licenses.</p>
<h2>License</h2>
<p><strong>league/commonmark</strong> is licensed under the BSD-3 license.  See the <code>LICENSE</code> file for more details.</p>
<h2>Governance</h2>
<p>This project is primarily maintained by <a href="https://www.twitter.com/colinodell">Colin O'Dell</a>.  Members of the <a href="https://thephpleague.com">PHP League</a> Leadership Team may occasionally assist with some of these duties.</p>

league/commonmark

Join the chat at https://gitter.im/thephpleague/commonmark

Latest Version Total Downloads Software License Build Status Coverage Status Quality Score SensioLabs Insight CII Best Practices

league/commonmark is a PHP-based 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).

Goals

  • Fully support the CommonMark spec (100% compliance)
  • Match the C and JavaScript implementations of CommonMark to make a logical and similar API
  • Continuously improve performance without sacrificing quality or compliance
  • Provide an extensible parser/renderer which users may customize as needed

Installation

This project can be installed via Composer:

$ composer require league/commonmark

Note: See Versioning for important information on which version constraints you should use.

Basic Usage

The 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>

:warning: Security warning: If you will be parsing untrusted input from users, please consider setting the html_input and allow_unsafe_links options. See https://commonmark.thephpleague.com/security/ for more details.

Advanced Usage & Customization

The actual conversion process requires two steps:

  1. Parsing the Markdown input into an AST
  2. Rendering the AST document as HTML

Although the CommonMarkConverter wrapper simplifies this process for you, advanced users will likely want to do this themselves:

use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;

// Obtain a pre-configured Environment with all the CommonMark parsers/renderers ready-to-go
$environment = Environment::createCommonMarkEnvironment();

// Optional: Add your own parsers, renderers, extensions, etc. (if desired)
// For example:  $environment->addInlineParser(new TwitterHandleParser());

// Define your configuration:
$config = ['html_input' => 'escape'];

// Create the converter
$converter = new CommonMarkConverter($config, $environment);

// Here's our sample input
$markdown = '# Hello World!';

// Let's render it!
echo $converter->convertToHtml($markdown);

// The output should be:
// <h1>Hello World!</h1>

This approach allows you to access/modify the AST before rendering it.

You can also add custom parsers/renderers by registering them with the Environment class. The documentation provides several customization examples such as:

You can also reference the core CommonMark parsers/renderers as they use the same functionality available to you.

Documentation

Documentation can be found at commonmark.thephpleague.com.

Related Packages

Integrations

CommonMark Extras

You can find several examples of useful extensions and customizations in the league/commonmark-extras package. You can add them to your parser or use them as examples to develop your own custom features.

Community Extensions

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

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

Compatibility with CommonMark

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.15.5 and higher supports version 0.28 of the CommonMark spec.

(This package is not part of CommonMark, but rather a compatible derivative.)

Testing

$ ./vendor/bin/phpunit

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

Versioning

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.16. This is equivalent to >=0.16.0 <0.17.0.

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 to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like ~0.16, >0.16, etc. I personally promise to never break this specific class in any future 0.x release.

Stability

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 both CommonMark and this project are considered stable (see outstanding CommonMark spec issues). 0.x.y will be used until that happens.

Contributing

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.

Security

If you discover any security related issues, please email your report privately to [email protected] instead of using the issue tracker.

Credits & Acknowledgements

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.

Also a huge thank you to JetBrains for supporting the development of this project with complimentary PhpStorm licenses.

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.

<h1>league/commonmark</h1>

<p><a href="https://gitter.im/thephpleague/commonmark?utm_source=badge&amp;utm_medium=badge&amp;utm_campaign=pr-badge&amp;utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Join the chat at https://gitter.im/thephpleague/commonmark" /></a></p>

<p><a href="https://packagist.org/packages/league/commonmark"><img src="https://img.shields.io/packagist/v/league/commonmark.svg?style=flat-square" alt="Latest Version" /></a>
<a href="https://packagist.org/packages/league/commonmark"><img src="https://img.shields.io/packagist/dt/league/commonmark.svg?style=flat-square" alt="Total Downloads" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-BSD--3-brightgreen.svg?style=flat-square" alt="Software License" /></a>
<a href="https://travis-ci.org/thephpleague/commonmark"><img src="https://img.shields.io/travis/thephpleague/commonmark/master.svg?style=flat-square" alt="Build Status" /></a>
<a href="https://scrutinizer-ci.com/g/thephpleague/commonmark/code-structure"><img src="https://img.shields.io/scrutinizer/coverage/g/thephpleague/commonmark.svg?style=flat-square" alt="Coverage Status" /></a>
<a href="https://scrutinizer-ci.com/g/thephpleague/commonmark"><img src="https://img.shields.io/scrutinizer/g/thephpleague/commonmark.svg?style=flat-square" alt="Quality Score" /></a>
<a href="https://insight.sensiolabs.com/projects/9bf971c0-458f-4a19-9898-127728dbd65d"><img src="https://img.shields.io/sensiolabs/i/9bf971c0-458f-4a19-9898-127728dbd65d.svg?style=flat-square" alt="SensioLabs Insight" /></a>
<a href="https://bestpractices.coreinfrastructure.org/projects/126"><img src="https://bestpractices.coreinfrastructure.org/projects/126/badge" alt="CII Best Practices" /></a></p>

<p><strong>league/commonmark</strong> is a PHP-based Markdown parser created by <a href="https://www.twitter.com/colinodell">Colin O'Dell</a> which supports the full <a href="http://commonmark.org/">CommonMark</a> spec.  It is based on the <a href="https://github.com/jgm/commonmark.js">CommonMark JS reference implementation</a> by <a href="http://johnmacfarlane.net">John MacFarlane</a> &#40;<a href="https://github.com/jgm">@jgm</a>&#41;.</p>

<h2>Goals</h2>

<ul>
<li>Fully support the CommonMark spec (100% compliance)</li>
<li>Match the C and JavaScript implementations of CommonMark to make a logical and similar API</li>
<li>Continuously improve performance without sacrificing quality or compliance</li>
<li>Provide an extensible parser/renderer which users may customize as needed</li>
</ul>

<h2>Installation</h2>

<p>This project can be installed via <a href="https://getcomposer.org/">Composer</a>:</p>

<pre><code class="bash">$ composer require league/commonmark
</code></pre>

<p><strong>Note:</strong> See <a href="#versioning">Versioning</a> for important information on which version constraints you should use.</p>

<h2>Basic Usage</h2>

<p>The <code>CommonMarkConverter</code> class provides a simple wrapper for converting CommonMark to HTML:</p>

<pre><code class="php">use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter();
echo $converter-&gt;convertToHtml('# Hello World!');

// &lt;h1&gt;Hello World!&lt;/h1&gt;
</code></pre>

<p>:warning: <strong>Security warning:</strong> If you will be parsing untrusted input from users, please consider setting the <code>html_input</code> and <code>allow_unsafe_links</code> options. See <a href="https://commonmark.thephpleague.com/security/">https://commonmark.thephpleague.com/security/</a> for more details.</p>

<h2>Advanced Usage &amp; Customization</h2>

<p>The actual conversion process requires two steps:</p>

<ol>
<li>Parsing the Markdown input into an AST</li>
<li>Rendering the AST document as HTML</li>
</ol>

<p>Although the <code>CommonMarkConverter</code> wrapper simplifies this process for you, advanced users will likely want to do this themselves:</p>

<pre><code class="php">use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;

// Obtain a pre-configured Environment with all the CommonMark parsers/renderers ready-to-go
$environment = Environment::createCommonMarkEnvironment();

// Optional: Add your own parsers, renderers, extensions, etc. (if desired)
// For example:  $environment-&gt;addInlineParser(new TwitterHandleParser());

// Define your configuration:
$config = ['html_input' =&gt; 'escape'];

// Create the converter
$converter = new CommonMarkConverter($config, $environment);

// Here's our sample input
$markdown = '# Hello World!';

// Let's render it!
echo $converter-&gt;convertToHtml($markdown);

// The output should be:
// &lt;h1&gt;Hello World!&lt;/h1&gt;
</code></pre>

<p>This approach allows you to access/modify the AST before rendering it.</p>

<p>You can also add custom parsers/renderers by <a href="https://commonmark.thephpleague.com/customization/environment/">registering them with the <code>Environment</code> class</a>.
The <a href="https://commonmark.thephpleague.com/">documentation</a> provides several <a href="https://commonmark.thephpleague.com/customization/overview/#examples">customization examples</a> such as:</p>

<ul>
<li><a href="https://commonmark.thephpleague.com/customization/inline-parsing#example-1---twitter-handles">Parsing Twitter handles into profile links</a></li>
<li><a href="https://commonmark.thephpleague.com/customization/inline-parsing#example-2---emoticons">Converting smilies into emoticon images</a></li>
</ul>

<p>You can also reference the core CommonMark parsers/renderers as they use the same functionality available to you.</p>

<h2>Documentation</h2>

<p>Documentation can be found at <a href="https://commonmark.thephpleague.com/">commonmark.thephpleague.com</a>.</p>

<h2>Related Packages</h2>

<h3>Integrations</h3>

<ul>
<li><a href="https://github.com/gourmet/common-mark">CakePHP 3</a></li>
<li><a href="https://www.drupal.org/project/markdown">Drupal 7 &amp; 8</a></li>
<li><a href="https://github.com/GrahamCampbell/Laravel-Markdown">Laravel 4 &amp; 5</a></li>
<li><a href="https://github.com/bcremer/sculpin-commonmark-bundle">Sculpin</a></li>
<li><a href="https://github.com/webuni/commonmark-bundle">Symfony</a></li>
<li><a href="https://github.com/webuni/commonmark-twig-renderer">Twig</a></li>
</ul>

<h3>CommonMark Extras</h3>

<p>You can find several examples of useful extensions and customizations in the <a href="https://github.com/thephpleague/commonmark-extras">league/commonmark-extras package</a>.  You can add them to your parser or use them as examples to <a href="https://commonmark.thephpleague.com/customization/overview/">develop your own custom features</a>.</p>

<h3>Community Extensions</h3>

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

<ul>
<li><a href="https://github.com/dshafik/markua">Markua</a> - Markdown parser for PHP which intends to support the full Markua spec.</li>
<li><a href="https://github.com/webuni/commonmark-table-extension">CommonMark Table Extension</a> - Adds the ability to create tables in CommonMark documents.</li>
<li><a href="https://github.com/webuni/commonmark-attributes-extension">CommonMark Attributes Extension</a> - Adds a syntax to define attributes on the various HTML elements.</li>
<li><a href="https://github.com/AltThree/Emoji">Alt Three Emoji</a> An emoji parser for CommonMark.</li>
<li><a href="https://github.com/uafrica/commonmark-ext">uafrica/commonmark-ext</a> - Adds strikethrough support.</li>
<li><a href="https://github.com/OWS/commonmark-sup-sub-extensions">Sup Sub extensions</a> - Adds support of superscript and subscript (<code>&lt;sup&gt;</code> and <code>&lt;sub&gt;</code> HTML tags)</li>
</ul>

<p>If you build your own, feel free to submit a PR to add it to this list!</p>

<h3>Others</h3>

<p>Check out the other cool things people are doing with <code>league/commonmark</code>: <a href="https://packagist.org/packages/league/commonmark/dependents">https://packagist.org/packages/league/commonmark/dependents</a></p>

<h2>Compatibility with CommonMark</h2>

<p>This project aims to fully support the entire <a href="http://spec.commonmark.org/">CommonMark spec</a>. Other flavors of Markdown may work but are not supported.  Any/all changes made to the <a href="http://spec.commonmark.org/">spec</a> or <a href="https://github.com/jgm/commonmark.js">JS reference implementation</a> should eventually find their way back into this codebase.</p>

<p>league/commonmark 0.15.5 and higher supports version 0.28 of the <a href="http://spec.commonmark.org/">CommonMark spec</a>.</p>

<p>(This package is <strong>not</strong> part of CommonMark, but rather a compatible derivative.)</p>

<h2>Testing</h2>

<pre><code class="bash">$ ./vendor/bin/phpunit
</code></pre>

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

<h2>Performance Benchmarks</h2>

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

<pre><code class="bash">$ ./tests/benchmark/benchmark.php
</code></pre>

<h2>Versioning</h2>

<p><a href="http://semver.org/">SemVer</a> will be followed closely.  0.x.0 versions will introduce breaking changes to the codebase, so be careful which version constraints you use. <strong>It's highly recommended that you use <a href="https://getcomposer.org/doc/articles/versions.md#caret">Composer's caret operator</a> to ensure compatibility</strong>; for example: <code>^0.16</code>.  This is equivalent to <code>&gt;=0.16.0 &lt;0.17.0</code>.</p>

<p>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.</p>

<p>If you're only using the <code>CommonMarkConverter</code> class to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like <code>~0.16</code>, <code>&gt;0.16</code>, etc.  I personally promise to never break this specific class in any future 0.x release.</p>

<h2>Stability</h2>

<p>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 <code>@api</code> are not expected to change, but other methods/classes might.</p>

<p>Major release 1.0.0 will be reserved for when both CommonMark and this project are considered stable (see <a href="http://talk.commonmark.org/t/issues-to-resolve-before-1-0-release/1287">outstanding CommonMark spec issues</a>).  0.x.y will be used until that happens.</p>

<h2>Contributing</h2>

<p>If you encounter a bug in the spec, please report it to the <a href="http://commonmark.org/">CommonMark</a> project.  Any resulting fix will eventually be implemented in this project as well.</p>

<p>For now, I'd like to maintain similar logic as the <a href="https://github.com/jgm/commonmark.js">JS reference implementation</a> until everything is stable.  I'll gladly accept any contributions which:</p>

<ul>
<li>Mirror fixes made to the <a href="https://github.com/jgm/commonmark.js">reference implementation</a></li>
<li>Optimize existing methods or regular expressions</li>
<li>Fix issues with adhering to the spec examples</li>
</ul>

<p>Major refactoring should be avoided for now so that we can easily follow updates made to <a href="https://github.com/jgm/commonmark.js">the reference implementation</a>.  This restriction will likely be lifted once the CommonMark specs and implementations are considered stable.</p>

<p>Please see <a href="https://github.com/thephpleague/commonmark/blob/master/CONTRIBUTING.md">CONTRIBUTING</a> for additional details.</p>

<h2>Security</h2>

<p>If you discover any security related issues, please email your report privately to [email protected] instead of using the issue tracker.</p>

<h2>Credits &amp; Acknowledgements</h2>

<ul>
<li><a href="https://www.twitter.com/colinodell">Colin O'Dell</a></li>
<li><a href="https://github.com/jgm">John MacFarlane</a></li>
<li><a href="https://github.com/thephpleague/commonmark/contributors">All Contributors</a></li>
</ul>

<p>This code is a port of the <a href="https://github.com/jgm/commonmark.js">CommonMark JS reference implementation</a> which is written, maintained and copyrighted by <a href="http://johnmacfarlane.net">John MacFarlane</a>.  This project simply wouldn't exist without his work.</p>

<p>Also a huge thank you to <a href="https://www.jetbrains.com/">JetBrains</a> for supporting the development of this project with complimentary <a href="https://www.jetbrains.com/phpstorm/">PhpStorm</a> licenses.</p>

<h2>License</h2>

<p><strong>league/commonmark</strong> is licensed under the BSD-3 license.  See the <code>LICENSE</code> file for more details.</p>

<h2>Governance</h2>

<p>This project is primarily maintained by <a href="https://www.twitter.com/colinodell">Colin O'Dell</a>.  Members of the <a href="https://thephpleague.com">PHP League</a> Leadership Team may occasionally assist with some of these duties.</p>

league/commonmark

Join the chat at https://gitter.im/thephpleague/commonmark

Latest Version Total Downloads Software License Build Status Coverage Status Quality Score SensioLabs Insight CII Best Practices

league/commonmark is a PHP-based 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).

Goals

  • Fully support the CommonMark spec (100% compliance)
  • Match the C and JavaScript implementations of CommonMark to make a logical and similar API
  • Continuously improve performance without sacrificing quality or compliance
  • Provide an extensible parser/renderer which users may customize as needed

Installation

This project can be installed via Composer:

$ composer require league/commonmark

Note: See Versioning for important information on which version constraints you should use.

Basic Usage

The 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>

:warning: Security warning: If you will be parsing untrusted input from users, please consider setting the html_input and allow_unsafe_links options. See https://commonmark.thephpleague.com/security/ for more details.

Advanced Usage & Customization

The actual conversion process requires two steps:

  1. Parsing the Markdown input into an AST
  2. Rendering the AST document as HTML

Although the CommonMarkConverter wrapper simplifies this process for you, advanced users will likely want to do this themselves:

use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;

// Obtain a pre-configured Environment with all the CommonMark parsers/renderers ready-to-go
$environment = Environment::createCommonMarkEnvironment();

// Optional: Add your own parsers, renderers, extensions, etc. (if desired)
// For example:  $environment->addInlineParser(new TwitterHandleParser());

// Define your configuration:
$config = ['html_input' => 'escape'];

// Create the converter
$converter = new CommonMarkConverter($config, $environment);

// Here's our sample input
$markdown = '# Hello World!';

// Let's render it!
echo $converter->convertToHtml($markdown);

// The output should be:
// <h1>Hello World!</h1>

This approach allows you to access/modify the AST before rendering it.

You can also add custom parsers/renderers by registering them with the Environment class. The documentation provides several customization examples such as:

You can also reference the core CommonMark parsers/renderers as they use the same functionality available to you.

Documentation

Documentation can be found at commonmark.thephpleague.com.

Related Packages

Integrations

CommonMark Extras

You can find several examples of useful extensions and customizations in the league/commonmark-extras package. You can add them to your parser or use them as examples to develop your own custom features.

Community Extensions

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

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

Compatibility with CommonMark

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.15.5 and higher supports version 0.28 of the CommonMark spec.

(This package is not part of CommonMark, but rather a compatible derivative.)

Testing

$ ./vendor/bin/phpunit

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

Versioning

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.16. This is equivalent to >=0.16.0 <0.17.0.

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 to convert Markdown (no other class references, custom parsers, etc.), then it should be safe to use a broader constraint like ~0.16, >0.16, etc. I personally promise to never break this specific class in any future 0.x release.

Stability

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 both CommonMark and this project are considered stable (see outstanding CommonMark spec issues). 0.x.y will be used until that happens.

Contributing

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.

Security

If you discover any security related issues, please email your report privately to [email protected] instead of using the issue tracker.

Credits & Acknowledgements

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.

Also a huge thank you to JetBrains for supporting the development of this project with complimentary PhpStorm licenses.

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.