Block handlers

• Part of: LH Content Converter

Other plugins can turn parts of Markdown or HTML into their own blocks when content is converted to blocks. LH Mermaid uses this so a Mermaid diagram written in Markdown or HTML lands as its Mermaid Diagram block, and any plugin with a block the conversion library has no mapping for can do the same.

Add a handler to the lh_content_converter_block_handlers filter, which takes and returns an array of callables. Each handler is called with the HTML and a claim function, and returns the HTML. Markdown has already been converted to HTML, so a code fence arrives as a pre element holding a code element with a language class. For each element it claims, the handler calls the claim function with the block markup it wants, and puts the placeholder it gets back in place of the element. LH Mermaid’s Lh_Mermaid_Block::claim_diagrams() is a worked example.

• The placeholder is a paragraph of its own, so claim only elements that can stand as a block where they are.
• Once the library has run, each placeholder’s paragraph block is swapped for the block markup exactly as given, so give what the block editor would save.
• Handlers run before code blocks are protected, so a handler can claim a fenced code block.
• If a placeholder isn’t found exactly once afterwards, the conversion fails with the lh_content_converter_block_restore_failed error rather than return content that can’t be trusted.

Handlers only apply to conversions to blocks, and every caller gets them: the post abilities, the knowledge base, LH Email drafts and LH Presentations slides.