v2 Roadmap

[colinodell]

My current wishlist for v2:

• AST stuff split into its own namespace or package
• Block and inline elements split into their own package (to enable sharing with league/html-to-markdown)? this is probably a "duplicate" of the AST split above
• Refactor how data is stored on AST elements; maybe use the data array more heavily?
• Extract some of the parsing logic out of the block/inline elements and into the parsers (similar to Atlassian's Java fork) and re-evaluate Resolve parent class #222
• Drop PHP 5.6 support
• Parameter/return types everywhere
• Two-way XML conversion
• Review other CommonMark implementations for other improvement ideas
• Pass phpstan checks at a higher level
• See whether stream/generator inputs make sense (they don't)
• Other big-ticket items like Investigate container vs tip #186, Revisit and finalize the AST implementation #232, and Convert to HTML without wrapping in an HTML element #312
• We sometimes call AbstractBlock elements on variables which contain Node. These are virtually always AbstractBlock elements though. See if we need to move some methods between these and/or tighten up our type hints.

I'll gradually refine this list as progress and decisions are made and spin it off into a milestone. Just wanted a place to collect my thoughts for now.

[Niklan]

I think library is need a bit more documentation with examples like this one, because at first time, this was a mess for me, what is going on. Most of the comments in source is just parameter names with types.

Many things works very tricky to understand, like default markdown links and images is handled via two different parsers for both cases OpenBracketParser and CloseBracketParser. I get it, but will be great, if those tricks with delimiter stack was documented.

Will be nice to see more detailed descriptions for parser, context and cursor methods at https://commonmark.thephpleague.com

Hope to see documentation improvements in v2!

[colinodell]

@Niklan Documentation has been significantly improved! https://commonmark.thephpleague.com If there's anything else you'd like to see, please let me know in #351.

[Niklan]

Looks cool! :) I think it will be easier for newcomers to understand what is going on.

I also have a question about https://commonmark.thephpleague.com/0.18/customization/cursor/ since we speak about documentation here.

As I understand $cursor is always work with the current line? I tried yesterday to move a cursor to the next line, and it remains on an initial line just at the end.

I mentioned earlier, I created custom BlockParser for such syntax:

> [!NOTE]
>
> Some content.

I trying to make the second line, after > [!NOTE] to be to be empty with just >, if it's not, stop parsing since it will be "not valid" markup for my syntax.

I tried to move a cursor to the next line in AbstractBlockParser::parse(), but as mentioned above, looks like it's not possible.

If it true, I think it worth to mention that cursor works only with the current line.

And I don't understand how to implement my condition for syntax. Maybe handle it with Element::matchesNextLine(), but how to fail block in this case and remove it from the render, since it not valid and let other parsers try to parse it, like blockquote. Is there something like DlimiterStack from inline parsers?

It's not important for me, I just tried to do it for fun and can't handle it.

[colinodell]

I'm replacing this with an actual milestone: https://github.com/thephpleague/commonmark/milestone/15 All planned features will be moved to new issues and PRs under that milestone, instead of having a checklist here.