Documentation 2.0

[aidantwoods]

This isn't yet complete, but is a start at documenting some of the updated internals.

[aidantwoods]

Really good so far, the only thing I can think of may confuse some people is when using extensions the example in this doc doesn't show you where you get new State from so by running the code example directly will return a error

Thanks for taking the time to review! I think I still need to add some more detail about adding custom blocks and inlines, and then also some explanation of the mechanics around parsing and interpreting objects like Context, Line, Lines, and Excerpt. And then also the different interfaces Blocks and Inlines can implement (e.g. ContinuableBlock or BacktrackingInline) that allow opting into some extra parsing features.

[BenjaminHoegh]

A little question, while I was working on updating ParsedownMath to work with 2.0 I was hit by a question, how do you add a closing marker? As LaTeX doesn't use the same marker for both opening and closing.

[aidantwoods]

Not sure whether you're doing a block or an inline at the moment: for either case though the reason that only a beginning marker is setup is because that's how Parsedown decides when to hand off the the individual parser for each block / inline.

Assuming you're talking about blocks here? By default these would only span a single line (see Header, which only implements Block). For a block to span multiple lines, it needs to implement ContinuableBlock, in which case the advance method will be called for that block so that it can parse the next line until that fails: so you'd just need to detect an end marker in that function and return null after that.

In FencedCode, this is done by detecting the end marker (note the true at the end of the arg list)

https://github.com/erusev/parsedown/blob/79effc4ae2a7d0d999b3b18c7b14ad1d1333427a/src/Components/Blocks/FencedCode.php#L92-L96

This then ends up being stored in $this->isComplete, so when Parsedown next calls advance, null is just returned straight away to indicate the block cannot be continued.

https://github.com/erusev/parsedown/blob/79effc4ae2a7d0d999b3b18c7b14ad1d1333427a/src/Components/Blocks/FencedCode.php#L82-L86

For inlines the process is a little different as the entire inline gets parsed in one go: essentially just a case of storing the correct width of the inline to let Parsedown know where it ends, e.g.

https://github.com/erusev/parsedown/blob/79effc4ae2a7d0d999b3b18c7b14ad1d1333427a/src/Components/Inlines/Strikethrough.php#L35-L44

[BenjaminHoegh]

You are absolutely amazing

[BenjaminHoegh]

I must say I have been enjoying updating parsedownMath for v2. When you first get how the new setup works, it is so easy to develop new functionality and so simple compared to v1. Great job I much say

[aidantwoods]

I must say I have been enjoying updating parsedownMath for v2. When you first get how the new setup works, it is so easy to develop new functionality and so simple compared to v1. Great job I much say

Thanks! That's really re-assuring feedback :)

Any parts that you feel it would be worth going over in extra detail, for when I finish these docs?

[BenjaminHoegh]

I must say I have been enjoying updating parsedownMath for v2. When you first get how the new setup works, it is so easy to develop new functionality and so simple compared to v1. Great job I much say

Thanks! That's really re-assuring feedback :)

Any parts that you feel it would be worth going over in extra detail, for when I finish these docs?

Hmm good question, I think it may be the State object as this is a really important part

[aidantwoods]

Thanks @BenjaminHoegh, I've added a little more of an explanation in 6be4366, hopefully that is enough! 😄