Add newer GFM features about commonmark

[colinodell]

I built a rough working prototype of this.

That's awesome!

Any interest including in this repo? If not, no problem, I can release as a separate package.

I'm hesitant to include this here right now because:

1. It's technically not (yet?) part of GFM, so it shouldn't be included as part of our GFM extension
2. There's no consensus that GitHub's admonitions should be the "standardized" way to implement them (there are other formats out there)
3. There's no spec for this, and reverse-engineering the edge cases around GitHub's implementation doesn't sound like a fun time.

But if you do release it as a separate package I'd be happy to link to it from the README and/or docs to help other users find it!

(Sorry for the delayed response here)

[colinodell]

Thanks for the suggestion!

Unfortunately, those features aren't actually part of the GFM spec: github/cmark-gfm#350 It's some kind of custom post-processing that GitHub does. I can certainly understand how parity with GitHub.com could be useful but without a spec to follow it's difficult to ensure we are handling every possible edge case the same exact way.

Therefore, it's unlikely that we'll incorporate that into this library. But if you find (or create) an extension for these we'd be happy to link to it!

[kbond]

Unfortunately, those features aren't actually part of the GFM spec

I think they might be in the future, they're considered "beta" right now.

@colinodell, I built a rough working prototype of this. Any interest including in this repo? If not, no problem, I can release as a separate package.

final class GFMNotesRenderer implements NodeRendererInterface
{
    private const NOTE_TYPES = [
        'NOTE',
        'TIP',
        'IMPORTANT',
        'WARNING',
        'CAUTION',
    ];

    private BlockQuoteRenderer $baseRenderer;

    public function __construct()
    {
        $this->baseRenderer = new BlockQuoteRenderer();
    }

    public function render(Node $node, ChildNodeRendererInterface $childRenderer)
    {
        if (!$parsed = $this->parseBlockQuote($node)) {
            return $this->baseRenderer->render($node, $childRenderer);
        }

        [$textNode, $type] = $parsed;

        $textNode->detach();

        $p = new Paragraph();
        $p->data->set('attributes', ['class' => 'markdown-note-label']);
        $p->appendChild(new Text(ucfirst($type)));

        $node->prependChild($p);
        $node->data->set('attributes', ['class' => sprintf('markdown-note markdown-note-%s', $type)]);

        return $this->baseRenderer->render($node, $childRenderer);
    }

    /**
     * @return array{0:Text,1:string}|null
     */
    private function parseBlockQuote(Node $node): ?array
    {
        $textNode = $node->firstChild()?->firstChild();

        if (!$textNode instanceof Text || !preg_match('#^\[!([A-Z]+)]$#', $textNode->getLiteral(), $matches)) {
            return null;
        }

        $type = $matches[1];

        if (!in_array($type, self::NOTE_TYPES, true)) {
            return null;
        }

        return [$textNode, strtolower($type)];
    }
}