From a5334733256e11b827c72905a7b06b636f20d455 Mon Sep 17 00:00:00 2001
From: Andy Clifford <andrew.clifford@hotmail.com>
Date: Thu, 12 Oct 2023 13:11:22 +1300
Subject: [PATCH] Markdoc Integration allowIndentation option

Added allowIndentation to the markdoc integration options. This allows indentation of markdoc tags for better readability without allowing raw HTML in Markdoc files.
---
 .changeset/hip-rockets-glow.md                |  5 +++
 packages/integrations/markdoc/README.md       | 34 +++++++++++++++
 packages/integrations/markdoc/src/options.ts  |  1 +
 .../integrations/markdoc/src/tokenizer.ts     |  6 ++-
 .../astro.config.mjs                          |  7 ++++
 .../markdoc.config.ts                         | 26 ++++++++++++
 .../package.json                              |  9 ++++
 .../src/components/Code.astro                 | 12 ++++++
 .../src/components/CustomMarquee.astro        |  1 +
 .../blog/with-indented-components.mdoc        | 24 +++++++++++
 .../src/pages/index.astro                     | 19 +++++++++
 .../integrations/markdoc/test/render.test.js  | 42 +++++++++++++++++++
 pnpm-lock.yaml                                |  9 ++++
 13 files changed, 194 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/hip-rockets-glow.md
 create mode 100644 packages/integrations/markdoc/test/fixtures/render-with-indented-components/astro.config.mjs
 create mode 100644 packages/integrations/markdoc/test/fixtures/render-with-indented-components/markdoc.config.ts
 create mode 100644 packages/integrations/markdoc/test/fixtures/render-with-indented-components/package.json
 create mode 100644 packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/components/Code.astro
 create mode 100644 packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/components/CustomMarquee.astro
 create mode 100644 packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/content/blog/with-indented-components.mdoc
 create mode 100644 packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/pages/index.astro

diff --git a/.changeset/hip-rockets-glow.md b/.changeset/hip-rockets-glow.md
new file mode 100644
index 0000000000000..c05314d30b0b8
--- /dev/null
+++ b/.changeset/hip-rockets-glow.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/markdoc': minor
+---
+
+Added allowIndentation as a markdoc integration option to enable better readability
diff --git a/packages/integrations/markdoc/README.md b/packages/integrations/markdoc/README.md
index da575acc226f2..8fc9d057c6487 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.
 
+### `allowIndentation`
+
+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 allowIndentation option.
+
+```diff lang="js" "allowIndentation: true"
+  // astro.config.mjs
+  import { defineConfig } from 'astro/config';
+  import markdoc from '@astrojs/markdoc';
+
+  export default defineConfig({
+    // ...
++   integrations: [markdoc({ allowIndentation: 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.
diff --git a/packages/integrations/markdoc/src/options.ts b/packages/integrations/markdoc/src/options.ts
index de0926cbbf2bb..2f527e41219d4 100644
--- a/packages/integrations/markdoc/src/options.ts
+++ b/packages/integrations/markdoc/src/options.ts
@@ -1,3 +1,4 @@
 export interface MarkdocIntegrationOptions {
 	allowHTML?: boolean;
+	allowIndentation?: boolean;
 }
diff --git a/packages/integrations/markdoc/src/tokenizer.ts b/packages/integrations/markdoc/src/tokenizer.ts
index 02719b36355c1..f2529d664cb20 100644
--- a/packages/integrations/markdoc/src/tokenizer.ts
+++ b/packages/integrations/markdoc/src/tokenizer.ts
@@ -15,11 +15,15 @@ export function getMarkdocTokenizer(options: MarkdocIntegrationOptions | undefin
 		};
 
 		if (options?.allowHTML) {
-			// we want to allow indentation for Markdoc tags that are interleaved inside HTML block elements
+			// allow indentation for Markdoc tags that are interleaved inside HTML block elements
 			tokenizerOptions.allowIndentation = true;
 			// enable HTML token detection in markdown-it
 			tokenizerOptions.html = true;
 		}
+		if (options?.allowIndentation) {
+			// allow indentation so nested Markdoc tags can be formatted for better readability
+			tokenizerOptions.allowIndentation = true;
+		}
 
 		_cachedMarkdocTokenizers[key] = new Markdoc.Tokenizer(tokenizerOptions);
 	}
diff --git a/packages/integrations/markdoc/test/fixtures/render-with-indented-components/astro.config.mjs b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/astro.config.mjs
new file mode 100644
index 0000000000000..a4caef01a8251
--- /dev/null
+++ b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/astro.config.mjs
@@ -0,0 +1,7 @@
+import { defineConfig } from 'astro/config';
+import markdoc from '@astrojs/markdoc';
+
+// https://astro.build/config
+export default defineConfig({
+	integrations: [markdoc({ allowIndentation: true })],
+});
diff --git a/packages/integrations/markdoc/test/fixtures/render-with-indented-components/markdoc.config.ts b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/markdoc.config.ts
new file mode 100644
index 0000000000000..ffb264ed827d4
--- /dev/null
+++ b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/markdoc.config.ts
@@ -0,0 +1,26 @@
+import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
+
+export default defineMarkdocConfig({
+	nodes: {
+		fence: {
+			render: component('./src/components/Code.astro'),
+			attributes: {
+				language: { type: String },
+				content: { type: String },
+			},
+		},
+	},
+	tags: {
+		'marquee-element': {
+			render: component('./src/components/CustomMarquee.astro'),
+			attributes: {
+				direction: {
+					type: String,
+					default: 'left',
+					matches: ['left', 'right', 'up', 'down'],
+					errorLevel: 'critical',
+				},
+			},
+		},
+	},
+})
diff --git a/packages/integrations/markdoc/test/fixtures/render-with-indented-components/package.json b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/package.json
new file mode 100644
index 0000000000000..3c1d0a7b5cb3d
--- /dev/null
+++ b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "@test/markdoc-render-with-indented-components",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "@astrojs/markdoc": "workspace:*",
+    "astro": "workspace:*"
+  }
+}
diff --git a/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/components/Code.astro b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/components/Code.astro
new file mode 100644
index 0000000000000..18bf1399f22ea
--- /dev/null
+++ b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/components/Code.astro
@@ -0,0 +1,12 @@
+---
+import { Code } from 'astro/components';
+
+type Props = {
+	content: string;
+	language: string;
+}
+
+const { content, language } = Astro.props as Props;
+---
+
+<Code lang={language} code={content} />
diff --git a/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/components/CustomMarquee.astro b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/components/CustomMarquee.astro
new file mode 100644
index 0000000000000..3108b997354c9
--- /dev/null
+++ b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/components/CustomMarquee.astro
@@ -0,0 +1 @@
+<marquee data-custom-marquee {...Astro.props}><slot /></marquee>
diff --git a/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/content/blog/with-indented-components.mdoc b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/content/blog/with-indented-components.mdoc
new file mode 100644
index 0000000000000..a52b35fc444ba
--- /dev/null
+++ b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/content/blog/with-indented-components.mdoc
@@ -0,0 +1,24 @@
+---
+title: Post with indented components
+---
+
+## Post with indented components
+
+This uses a custom marquee component with a shortcode:
+
+{% marquee-element direction="right" %}
+	I'm a marquee too!
+
+	{% marquee-element direction="right" %}
+		I'm an indented marquee!
+
+		### I am an h3!
+	{% /marquee-element %}
+
+	And a nested code block:
+
+	```js
+	const isRenderedWithShiki = true;
+	```
+{% /marquee-element %}
+
diff --git a/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/pages/index.astro b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/pages/index.astro
new file mode 100644
index 0000000000000..0ae7ed4c9da32
--- /dev/null
+++ b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/src/pages/index.astro
@@ -0,0 +1,19 @@
+---
+import { getEntryBySlug } from "astro:content";
+
+const post = await getEntryBySlug('blog', 'with-indented-components');
+const { Content } = await post.render();
+---
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta http-equiv="X-UA-Compatible" content="IE=edge">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>Content</title>
+</head>
+<body>
+	<Content />	
+</body>
+</html>
diff --git a/packages/integrations/markdoc/test/render.test.js b/packages/integrations/markdoc/test/render.test.js
index 86ffcb7077ecf..97c441b857689 100644
--- a/packages/integrations/markdoc/test/render.test.js
+++ b/packages/integrations/markdoc/test/render.test.js
@@ -46,6 +46,19 @@ describe('Markdoc - render', () => {
 			await server.stop();
 		});
 
+		it('renders content - with indented components', async () => {
+			const fixture = await getFixture('render-with-indented-components');
+			const server = await fixture.startDevServer();
+
+			const res = await fixture.fetch('/');
+			const html = await res.text();
+
+			renderIndentedComponentsChecks(html);
+
+			await server.stop();
+
+		});
+
 		it('renders content - with `render: null` in document', async () => {
 			const fixture = await getFixture('render-null');
 			const server = await fixture.startDevServer();
@@ -87,6 +100,15 @@ describe('Markdoc - render', () => {
 			renderComponentsChecks(html);
 		});
 
+		it('renders content - with indented components', async () => {
+			const fixture = await getFixture('render-with-indented-components');
+			await fixture.build();
+
+			const html = await fixture.readFile('/index.html');
+
+			renderIndentedComponentsChecks(html);
+		});
+
 		it('renders content - with `render: null` in document', async () => {
 			const fixture = await getFixture('render-null');
 			await fixture.build();
@@ -125,6 +147,26 @@ function renderComponentsChecks(html) {
 	expect(pre.className).to.equal('astro-code github-dark');
 }
 
+/** @param {string} html */
+function renderIndentedComponentsChecks(html) {
+	const { document } = parseHTML(html);
+	const h2 = document.querySelector('h2');
+	expect(h2.textContent).to.equal('Post with indented components');
+
+	// Renders custom shortcode components
+	const marquees = document.querySelectorAll('marquee');
+	expect(marquees.length).to.equal(2);
+
+	// Renders h3
+	const h3 = document.querySelector('h3');
+	expect(h3.textContent).to.equal('I am an h3!');
+
+	// Renders Astro Code component
+	const pre = document.querySelector('pre');
+	expect(pre).to.not.be.null;
+	expect(pre.className).to.equal('astro-code github-dark');
+}
+
 /** @param {string} html */
 function renderConfigChecks(html) {
 	const { document } = parseHTML(html);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 40672d815ff7b..bb4bbc5476ab2 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -3869,6 +3869,15 @@ importers:
         specifier: workspace:*
         version: link:../../../../../astro
 
+  packages/integrations/markdoc/test/fixtures/render-with-indented-components:
+    dependencies:
+      '@astrojs/markdoc':
+        specifier: workspace:*
+        version: link:../../..
+      astro:
+        specifier: workspace:*
+        version: link:../../../../../astro
+
   packages/integrations/markdoc/test/fixtures/variables:
     dependencies:
       '@astrojs/markdoc':