Ready to go beyond the basics of converting Markdown to HTML? This page describes some of the more advanced things you can customize this library to do.
Parsing and Rendering
The actual process of converting Markdown to HTML has several steps:
- Create an
Environment, adding whichever extensions/parser/renders you need
- Set custom configuration options within the
- Instantiate a
- Use the
DocParserto parse the Markdown input into an Abstract Syntax Tree (aka an “AST”)
- Use the
HtmlRendererto convert the AST
CommonMarkConverter handles all of this for you, but you can execute that process yourself if you wish:
use League\CommonMark\DocParser; use League\CommonMark\Environment; use League\CommonMark\HtmlRenderer; $environment = Environment::createCommonMarkEnvironment(); $environment->setConfig([ 'html_input' => 'strip', ]); $parser = new DocParser($environment); $htmlRenderer = new HtmlRenderer($environment); $markdown = '# Hello World!'; $document = $parser->parse($markdown); echo $htmlRenderer->renderBlock($document); // <h1>Hello World!</h1>
Feel free to swap out different components or add your own steps in between. However, the best way to customize this library is to create your own extensions which hook into the parsing and rendering steps - continue reading to see which kinds of extension points are available to you.
Add Custom Syntax with Parsers
Parsers examine the Markdown input and produce an abstract syntax tree (AST) of the document’s structure. This resulting AST contains both blocks (structural elements like paragraphs, lists, headers, etc) and inlines (words, spaces, links, emphasis, etc).
There are two main types of parsers:
The parsing approach is identical for both types - examine text at the current position (via the
Cursor) and determine if you can handle it;
if so, create the corresponding AST element,
otherwise you abort and the engine will try other parsers. If no parser succeeds then the current text is treated as plain text.
Simple delimiter-based inlines (like emphasis, strikethrough, etc.) can be parsed without needing a dedicated inline parser by leveraging the new Delimiter Processing functionality.
Once the Abstract Syntax Tree is parsed, you are free to access/manipulate it as needed before it’s passed into the rendering engine.
Customize HTML Output with Custom Renderers
Renders convert the parsed blocks/inlines from the AST representation into HTML. There are two types of renderers:
When registering these with the environment, you must tell it which block/inline classes it should handle. This allows you to essentially “swap out” built-in renderers with your own.
Some examples of what’s possible: