Question: how to render a <figure>?

[Spomky]

Hi,

I am creating an extension to render figures instead of simple images

<figure>
    <img src="https://octodex.github.com/images/stormtroopocat.jpg" alt="Stormtroopocat" title="The Stormtroopocat">
    <figcaption>A Stormtroopocat at work</figcaption>
</figure>

My first idea was to have such a markdown data:

![Stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg "The Stormtroopocat")
*A Stormtroopocat at work*

The mardown above will render the following HTML:

<p>
    <img src="https://octodex.github.com/images/stormtroopocat.jpg" alt="Stormtroopocat" title="The Stormtroopocat">
    <em>A Stormtroopocat at work</em>
<p>

Then, I should be able to the stucture p >img,em and convert it into figure > img,figcaption.
Am I correct or totally wrong?

[colinodell]

I think there are two possible ways you could implement this. You could do the type of conversion you're talking about, but a more-accurate approach might be to implement a custom parser.

Your proposed syntax looks very similar to setext headings - you have some content on the first line but it's the second line that determines whether or not it should be a caption. You could therefore implement a parser with similar logic - something like this:

<?php

namespace Your\Custom\Extension\Figure;

use League\CommonMark\Parser\Block\BlockStart;
use League\CommonMark\Parser\Block\BlockStartParserInterface;
use League\CommonMark\Parser\Cursor;
use League\CommonMark\Parser\MarkdownParserStateInterface;
use League\CommonMark\Util\RegexHelper;

final class FigureStartParser implements BlockStartParserInterface
{
    public function tryStart(Cursor $cursor, MarkdownParserStateInterface $parserState): ?BlockStart
    {
        // Skip if the line is indented code
        if ($cursor->isIndented()) {
            return BlockStart::none();
        }

        $cursor->advanceToNextNonSpaceOrTab();
        // Does this line start and end with an asterisk?
        if (! RegexHelper::matchFirst('/^\*.+\*[ \t]*$/', $cursor->getRemainder())) {
            return BlockStart::none();
        }

        // Was there paragraph content on the preceding line?
        $content = $parserState->getParagraphContent();
        if ($content === null) {
            // No, so this isn't a figure
            return BlockStart::none();
        }

        return BlockStart::of(new FigureParser($content))
            ->at($cursor)
            ->replaceActiveBlockParser();
    }
}

You'd also have to implement a block continue parser, custom node elements, and custom renderers to get this working, but you'd have more control over the parsing and reduce the likelihood of false positives.

Otherwise, if you want to go with the convert-existing-nodes route, check out the DocumentParsedEvent which lets you explore and manipulate the AST.