From 5af699c47955345e14f66f3863ff7db48dcd90a2 Mon Sep 17 00:00:00 2001
From: Colin O'Dell <colinodell@gmail.com>
Date: Fri, 23 Jun 2023 12:06:44 -0400
Subject: [PATCH] Add docs page about disabling features

---
 docs/2.4/customization/disabling-features.md | 67 ++++++++++++++++++++
 docs/_data/menu.yml                          |  1 +
 2 files changed, 68 insertions(+)
 create mode 100644 docs/2.4/customization/disabling-features.md

diff --git a/docs/2.4/customization/disabling-features.md b/docs/2.4/customization/disabling-features.md
new file mode 100644
index 0000000000..2b4e7ac3ed
--- /dev/null
+++ b/docs/2.4/customization/disabling-features.md
@@ -0,0 +1,67 @@
+---
+layout: default
+title: Disabling Features
+description: How to disable certain features of this library
+redirect_from:
+- /customization/disabling-features/
+---
+
+# 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`](/2.4/customization/environment/) in the first place.  This is exactly how the
+[`InlinesOnlyExtension`](/2.4/extensions/inlines-only/) 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](/2.4/customization/extensions/) 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:
+
+```markdown
+> This is a block quote
+```
+
+Would have the `>` character appear in the output HTML:
+
+```html
+<p>&gt; 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](/2.4/customization/event-dispatcher/#registering-listeners)
+(sort of like [this one](/2.4/customization/event-dispatcher/#example)) that will
+[iterate all parsed elements](/2.4/customization/abstract-syntax-tree/), locate the target nodes, and remove them
+by calling `$node->detach()`.
+
+There are three potential advantages to this approach:
+
+1. You don't need to create a custom extension class or prevent parsers from being registered
+2. You can selectively remove certain elements based on their properties (e.g. only remove heading levels 3-6) while keeping others
+3. 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](/2.4/customization/rendering/) 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:
+
+1. You still incur the overhead of parsing the elements that are eventually removed
+2. You'd need to register your custom renderer with a higher priority than the default renderer
+3. 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.
diff --git a/docs/_data/menu.yml b/docs/_data/menu.yml
index b8f81b1f40..6ec56126f5 100644
--- a/docs/_data/menu.yml
+++ b/docs/_data/menu.yml
@@ -44,6 +44,7 @@ version:
             'Abstract Syntax Tree': '/2.4/customization/abstract-syntax-tree/'
             'Rendering': '/2.4/customization/rendering/'
             'Slug Normalizer': '/2.4/customization/slug-normalizer/'
+            'Disabling Features': '/2.4/customization/disabling-features/'
     '2.3':
         Getting Started:
             'Overview': '/2.3/'