This is the documentation for version 2.5. Please consider upgrading your code to the latest stable version
Disabling Features
The CommonMark parser is designed to be highly configurable. You can disable certain features that you don’t want to have in your application. There are a few ways to do this, depending on your needs:
Avoiding Parsing
You cannot disable an already-registered parser, but you can prevent it from being registered with
the Environment in the first place. This is exactly how the
InlinesOnlyExtension works - it’s a copy of the CommonMarkCoreExtension class but
with the parsers we don’t want removed.
You can mirror this approach by defining your own custom extension class that registers only the specific parsers, renderers, etc. that you want.
The only potential downside to this approach is that any syntax for those disabled features will appear in the output. For example, if you were to prevent block quotes from being parsed, then the following Markdown:
> This is a block quote
Would have the > character appear in the output HTML:
<p>> This is a block quote</p>
This is probably fine for most use cases.
Removing Parsed Elements
An alternative approach is to keep the parser enabled, but remove the parsed elements from the AST before rendering.
You’d create an event listener
(sort of like this one) that will
iterate all parsed elements, locate the target nodes, and remove them
by calling $node->detach().
There are three potential advantages to this approach:
- You don’t need to create a custom extension class or prevent parsers from being registered
- You can selectively remove certain elements based on their properties (e.g. only remove heading levels 3-6) while keeping others
- The syntax and contents of the removed elements will not appear in the output HTML
The downside is that you still incur the overhead of parsing the elements that are eventually removed.
Override Rendering
The final approach is to keep the parser enabled, but override how the parsed elements are rendered. For example,
you could implement a custom renderer for certain elements that simply returns
something else (perhaps an empty string, or an HTML comment of <!-- REMOVED -->) instead of the HTML you don’t want.
This approach is not recommended because:
- You still incur the overhead of parsing the elements that are eventually removed
- You’d need to register your custom renderer with a higher priority than the default renderer
- You’d need to repeat this for every renderer that could potentially render the elements you want to remove
It should technically work though, if you really want to go this route.