From c5f5bf4dc0bab2e19ef562b648acfc91828bd4c9 Mon Sep 17 00:00:00 2001
From: Andy Clifford <andrew.clifford@hotmail.com>
Date: Wed, 11 Oct 2023 12:17:49 +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       | 33 +++++++++++++++
 packages/integrations/markdoc/src/options.ts  |  1 +
 .../integrations/markdoc/src/tokenizer.ts     |  6 ++-
 .../astro.config.mjs                          |  7 ++++
 .../markdoc.config.ts                         | 26 ++++++++++++
 .../package.json                              | 12 ++++++
 .../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                                | 13 ++++++
 13 files changed, 200 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 000000000..c05314d30
--- /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 da575acc2..f7db4074e 100644
--- a/packages/integrations/markdoc/README.md
+++ b/packages/integrations/markdoc/README.md
@@ -458,6 +458,39 @@ 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`
+
+Enables indentation of Markdoc tags for better readability.
+
+The allowIndentation option is experimental and is not enabled by default. When the option is enabled, it is not possible to use indent-based code blocks.
+
+```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 👋
+
+{% custom-tag %}
+  {% custom-tag %}
+    ### Tags can be indented for better readability
+
+    {% another-custom-tag %}
+      This is easier to read 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 de0926cbb..2f527e412 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 02719b363..f2529d664 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 000000000..a4caef01a
--- /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 000000000..ffb264ed8
--- /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 000000000..d205aba63
--- /dev/null
+++ b/packages/integrations/markdoc/test/fixtures/render-with-indented-components/package.json
@@ -0,0 +1,12 @@
+{
+  "name": "@test/markdoc-render-with-indented-components",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "@astrojs/markdoc": "workspace:*",
+    "astro": "workspace:*"
+  },
+  "devDependencies": {
+    "shiki": "^0.14.3"
+  }
+}
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 000000000..18bf1399f
--- /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 000000000..3108b9973
--- /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 000000000..a52b35fc4
--- /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 000000000..0ae7ed4c9
--- /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 86ffcb707..de2a522d2 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 indented h3
+	const h3 = document.querySelector('h3');
+	expect(h3.textContent).to.equal('I am an h3!');
+
+	// Renders indented 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 4d662e17b..8e57ba8e9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4019,6 +4019,19 @@ 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
+    devDependencies:
+      shiki:
+        specifier: ^0.14.3
+        version: 0.14.3
+
   packages/integrations/markdoc/test/fixtures/variables:
     dependencies:
       '@astrojs/markdoc':