After 5 years of development, 3,000,000 downloads, and 58 releases, I'm extremely pleased to announce that league/commonmark version 1.0.0 has been released!

What is league/commonmark?

league/commonmark is a highly-extensible PHP Markdown parser which is fully compliant with the CommonMark spec. It avoids some of the issues and funky edge cases that other Markdown parsers have while also allowing you to implement your own custom Markdown syntax to best suit your needs.

Why did this take so long?

The very first commit to this project was made almost 5 years ago, shortly after the CommonMark initiative was announced. Since then, the spec has undergone 29 major (0.x) revisions - many of which fundamentally changed how certain types of syntax are handled. This was especially true in the early days of the spec as serious issues were identified and ironed out.

Because the spec was largely unstable and subject to major changes, I originally planned to wait until the spec reached 1.0 stability before releasing 1.0.0 of this library. This wait ended up being longer than I expected.

There are still some unresolved issues with the CommonMark spec that need to be addressed before they release 1.0. Some of these will certainly change how certain Markdown inputs are handled. However, over the past several years, we've seen the core parsing logic gradually stabilize with each new release. So while I can't predict what changes might come in the future, I do feel fairly confident that our library's public API is unlikely to change much at this point.

Why didn't you wait longer?

This library has gone through 19 different 0.x releases over the years with each one introducing some breaking changes. This made it harder for extensions and end-users to stay up-to-date. Many of these changes were required to keep up with the underlying spec's changes (remember, they went through 29 0.x releases) while others were simply improvements on our own code base.

Because development of the spec has slowed down, and most of the important logic is unlikely to change much, I felt like now was a good time to put forth a stable release.

What does this mean for stability?

Three things:

1. We'll be staying on the 1.x branch for a while. I'm quite pleased with the improvements we've made to the code architecture and it should hopefully serve us well for a long time to come.
2. More minor updates == fewer breaking changes. It'll be even easier to keep your sites and applications up-to-date with the latest fixes and improvements.
3. Guaranteed support periods for older releases. Each new major and minor version will remain supported for several months.

What else is in 1.0.0?

In a nutshell, we've made the following changes since 0.19:

• Custom delimiters are much easier to add thanks to a major overhaul of the delimiter system
• An event dispatcher is now available, making it easier to hook into certain functionality without needing to extend or replace classes
• Most of the core classes now use interfaces, allowing you to easily swap out components or mock them in your tests
• Legacy cruft has been cleaned up

See our upgrading guide and https://commonmark.thephpleague.com/1.0/changelog/ for more information.

Awesome! How can I get it?

Simply bump your Composer version constraints to ^1.0!

And if you don't already have the library installed, simply run composer install league/commonmark and follow the basic usage documentation to get started!