league/commonmark
Extensible PHP Markdown parser supporting the full CommonMark spec and GitHub-Flavored Markdown. Works with PHP 7.4+ (mbstring) and provides simple converters to turn Markdown into HTML with configurable safety options.
layout: default title: Customization Overview description: An overview of the powerful customization features redirect_from:
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.
The actual process of converting Markdown to HTML has several steps:
Environment, adding whichever extensions/parser/renders/configuration you needMarkdownParser and HtmlRenderer using that EnvironmentMarkdownParser to parse the Markdown input into an Abstract Syntax Tree (aka an "AST")HtmlRenderer to convert the AST Document into HTMLThe MarkdownConverter class handles all of this for you, but you can execute that process yourself if you wish:
use League\CommonMark\Parser\MarkdownParser;
use League\CommonMark\Environment\Environment;
use League\CommonMark\Renderer\HtmlRenderer;
$environment = new Environment([
'html_input' => 'strip',
]);
$environment->addExtension(new CommonMarkCoreExtension());
$parser = new MarkdownParser($environment);
$htmlRenderer = new HtmlRenderer($environment);
$markdown = '# Hello World!';
$document = $parser->parse($markdown);
echo $htmlRenderer->renderDocument($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.
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.
Renderers convert the parsed blocks/inlines from the AST representation into HTML. 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:
How can I help you explore Laravel packages today?