Best Practices and Challenges in Extending CommonMark for Custom Use Cases (original) (raw)

Hi everyone,

I’ve been exploring CommonMark for a while now and really appreciate its clean, unambiguous spec and the way it strives for consistent Markdown parsing across implementations. I’m currently working on a project where I need to extend CommonMark with some custom syntax features tailored to specific domain needs (for example, custom containers, enhanced tables, or specialized inline annotations).

Before diving too deep, I wanted to ask the community about best practices or experiences around extending CommonMark in a way that maintains compatibility with the original spec but adds meaningful new capabilities. Specifically:

• How do you approach extending CommonMark syntax without breaking interoperability with other CommonMark parsers?
• Are there common pitfalls or challenges you’ve encountered when adding custom block or inline elements?
• Do you have recommendations for tools or parser libraries that are particularly flexible or well-suited for extensibility?
• How do you handle the documentation or communication of such extensions so that users and downstream consumers understand and can properly parse your custom Markdown?
• Finally, do you think the CommonMark spec itself could benefit from an official extension mechanism or syntax registration process?

I’m excited to hear your thoughts and learn from any examples or projects you’ve worked on that involved extending CommonMark. Also, if you have any experience or insights related to ccsp training in bangalore, I’d love to hear about that as well. Thanks in advance for sharing your insights!

Looking forward to a great discussion!

It’s a bummer that this topic hasn’t gotten more traction. I have thought about this as well, and I certainly can’t say I know any “best practices”, but I can point to a set of extensions that are used by probably 1000 people: https://github.com/cabo/kramdown-rfc.

In the future, I’ll probably create an extension that is based on the ideas there but is closer to CommonMark, but that probably won’t be soon. I’m interested in hearing from others how they have done their extensions.