After 96 releases, 368 pull requests, and over 48 million downloads, I'm pleased to share that the next major version of league/commonmark 2.0.0 stable is now generally available! 🎉🎉
You can install the latest version via Composer:
composer require league/commonmark:^2.0
What's new in 2.0?
There's so much to cover, but here are the key improvements and changes:
- Up to 50% faster and 21% less memory usage, especially when dealing with larger Markdown documents
- Three new extensions for Front Matter, Description Lists, and Default HTML Attributes
- A new XML renderer to simplify AST debugging
- Completely revamped parsing engine for faster speed and more precise parsing control (for blocks, inlines, and delimiters)
- A unified rendering approach for both blocks and inlines
- Compatibility with PSR-14 event dispatcher libraries
- Psalm purity markers throughout the codebase
- Minimal BC-breaks for most users
- Tons more!
Upgrading from 1.x
The upgrade process will vary based on whether you have custom functionality or are simply using the library as-is. I've therefore split the upgrading guide into three parts to help you understand the changes that impact you:
- For Consumers - you use the library as-is and maybe even enable some additional extensions
- For Integrators - you maintain an integration between this library and something else, like a CMS or framework
- For Developers - you write custom extensions and like to tinker under-the-hood
The Future of 1.x
Per the usual policies, the 1.6 branch will continue to receive bug fixes for at least 3 months and security updates for 6 months, if not longer, depending on the severity of any issues. No further minor releases (like 1.7.0) will be made, meaning that all new features and spec compliance updates will only be added to 2.0 and higher. You are therefore strongly encouraged to upgrade to the new version if/when you can.
If for any reason you can't upgrade immediately, that's alright - 1.6 is very stable and should work just fine until you're able to upgrade. And of course, if you're stuck on an older version of PHP you can keep using 1.6 too.
If you're using Laravel, note that support for league/commonmark v1 is being dropped in Larvel 9. Other frameworks and integrations will also like drop 1.x support from new major releases over the rest of this year.
Roadmap for 2.1 and 3.0
You didn't think development was over now that 2.0.0 is released, did you? We're already planning some exciting new features for future versions:
Coming in 2.1
Coming in 3.0
- Two-way conversion from Markdown/HTML/XML to Markdown/HTML/XML, including pretty-printing Markdown
- The ability to programmatically toggle task list items and save the updated Markdown
(The features above are subject to change)
Thank You
I owe a huge debt of thanks to everyone who helped make this possible, including (in no particular order):
- Every developer who has installed, used, shared, or contributed to this project
- Everyone in the PHP League for their mentorship and assistance over the years
- John MacFarlane, GitHub, Atlassian, and others for working on the CommonMark spec, GFM spec, and reference parsers that this project is based on
- Everyone who sponsors my open-source welcome, especially Geoff Thompson, Taylor Otwell, Dan Brown, Josh Bruce, and Spatie
- The entire PHP community
Support My Open-Source Development
You can now sponsor me on GitHub to support my open-source development and contributions! All contributions will be matched by GitHub.
