1 files changed, 34 insertions, 0 deletions
diff --git a/packages/integrations/markdoc/README.md b/packages/integrations/markdoc/README.md
index da575acc2..fa506b24a 100644
--- a/packages/integrations/markdoc/README.md
+++ b/packages/integrations/markdoc/README.md
@@ -458,6 +458,40 @@ To achieve a more Markdown-like experience, where HTML elements can be included
 > **Warning**
 > When `allowHTML` is enabled, HTML markup inside Markdoc documents will be rendered as actual HTML elements (including `<script>`), making attack vectors like XSS possible. Ensure that any HTML markup comes from trusted sources.
 
+### `ignoreIndentation`
+
+By default, any content that is indented by four spaces is treated as a code block. Unfortunately, this behavior makes it difficult to use arbitrary levels of indentation to improve the readability of documents with complex structure.
+
+When using nested tags in Markdoc, it can be helpful to indent the content inside of tags so that the level of depth is clear. To support arbitrary indentation, we have to disable the indent-based code blocks and modify several other markdown-it parsing rules that account for indent-based code blocks. These changes can be applied by enabling the ignoreIndentation option.
+
+```diff lang="js" "ignoreIndentation: true"
+  // astro.config.mjs
+  import { defineConfig } from 'astro/config';
+  import markdoc from '@astrojs/markdoc';
+
+  export default defineConfig({
+    // ...
++   integrations: [markdoc({ ignoreIndentation: true })],
+    //                       ^^^^^^^^^^^^^^^^^^^^^^^
+  });
+```
+
+```md
+# Welcome to Markdoc with indented tags 👋
+# Note: Can use either spaces or tabs for indentation
+
+{% custom-tag %}
+  {% custom-tag %}
+    ### Tags can be indented for better readability
+
+    {% another-custom-tag %}
+      This is easier to follow when there is a lot of nesting
+    {% /another-custom-tag %}
+
+  {% /custom-tag %}
+{% /custom-tag %}
+```
+
 ## Examples
 
 - The [Astro Markdoc starter template](https://github.com/withastro/astro/tree/latest/examples/with-markdoc) shows how to use Markdoc files in your Astro project.