Add newer GFM features

[jonaskohl]

Description

GitHub added a few new features to GFM, like alert blocks or inline color display. The GithubFlavoredMarkdownConverter should take these into account and add corresponding identifiers (i.e. CSS classes) to these elements to be able to style them accordingly. This is necessary to render markdown files pulled from GitHub as authentically as possible.

Example

For example, this:

> [!NOTE]
> This is a note

I'm `#0000FF` da ba dee...

should render like this:

[!NOTE] This is a note

I'm #0000FF da ba dee...

Did this project help you today? Did it make you happy in any way?

No response

[colinodell]

Thanks for the suggestion!

Unfortunately, those features aren't actually part of the GFM spec: https://github.com/github/cmark-gfm/issues/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)];
    }
}

[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)

[tomsommer]

@kbond would be cool with a separate package, one that perhaps also supports the squidfunk format, which I personally find superior.

[kbond]

@tomsommer here's where I've been working on extra extensions: https://github.com/kbond/commonmark-extensions