@astrojs/markdoc 0.0.3 → 0.0.5

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
-@astrojs/markdoc:build: cache hit, replaying output 30bf30e6debacf79
-@astrojs/markdoc:build: 
-@astrojs/markdoc:build: > @astrojs/markdoc@0.0.3 build /home/runner/work/astro/astro/packages/integrations/markdoc
-@astrojs/markdoc:build: > astro-scripts build "src/**/*.ts" && tsc
-@astrojs/markdoc:build: 
+@astrojs/markdoc:build: cache hit, replaying output 0cf4b43fcaef6989
+@astrojs/markdoc:build: 
+@astrojs/markdoc:build: > @astrojs/markdoc@0.0.5 build /home/runner/work/astro/astro/packages/integrations/markdoc
+@astrojs/markdoc:build: > astro-scripts build "src/**/*.ts" && tsc
+@astrojs/markdoc:build: 

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @astrojs/markdoc
 
+## 0.0.5
+
+### Patch Changes
+
+- [#6630](https://github.com/withastro/astro/pull/6630) [`cfcf2e2ff`](https://github.com/withastro/astro/commit/cfcf2e2ffdaa68ace5c84329c05b83559a29d638) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Support automatic image optimization for Markdoc images when using `experimental.assets`. You can [follow our Assets guide](https://docs.astro.build/en/guides/assets/#enabling-assets-in-your-project) to enable this feature in your project. Then, start using relative or aliased image sources in your Markdoc files for automatic optimization:
+
+  ```md
+  <!--Relative paths-->
+
+  ![The Milky Way Galaxy](../assets/galaxy.jpg)
+
+  <!--Or configured aliases-->
+
+  ![Houston smiling and looking cute](~/assets/houston-smiling.jpg)
+  ```
+
+- Updated dependencies [[`b7194103e`](https://github.com/withastro/astro/commit/b7194103e39267bf59dcd6ba00f522e424219d16), [`cfcf2e2ff`](https://github.com/withastro/astro/commit/cfcf2e2ffdaa68ace5c84329c05b83559a29d638), [`45da39a86`](https://github.com/withastro/astro/commit/45da39a8642d64eb318840b18dfc2b5ccc6561bc), [`7daef9a29`](https://github.com/withastro/astro/commit/7daef9a2993b5d457f3d243a1ebfd1dd383b3327)]:
+  - astro@2.1.7
+
+## 0.0.4
+
+### Patch Changes
+
+- [#6588](https://github.com/withastro/astro/pull/6588) [`f42f47dc6`](https://github.com/withastro/astro/commit/f42f47dc6a91cdb6534dab0ecbf9e8e85f00ba40) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Allow access to content collection entry information (including parsed frontmatter and the entry slug) from your Markdoc using the `$entry` variable:
+
+  ```mdx
+  ---
+  title: Hello Markdoc!
+  ---
+
+  # {% $entry.data.title %}
+  ```
+
+- [#6607](https://github.com/withastro/astro/pull/6607) [`86273b588`](https://github.com/withastro/astro/commit/86273b5881cc61ebee11d40280b4c0aba8f4bb2e) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Fix: Update Markdoc renderer internals to remove unneeded dependencies
+
+- [#6622](https://github.com/withastro/astro/pull/6622) [`b37b86540`](https://github.com/withastro/astro/commit/b37b865400e77e92878d7e150244acce47e933c6) Thanks [@paulrudy](https://github.com/paulrudy)! - Fix README instructions for installing Markdoc manually.
+
 ## 0.0.3
 
 ### Patch Changes

package/README.md

@@ -237,6 +237,20 @@ const { Content } = await entry.render();
 />
 ```
 
+### Access frontmatter and content collection information from your templates
+
+You can access content collection information from your Markdoc templates using the `$entry` variable. This includes the entry `slug`, `collection` name, and frontmatter `data` parsed by your content collection schema (if any). This example renders the `title` frontmatter property as a heading:
+
+```md
+---
+title: Welcome to Markdoc 👋
+---
+
+# {% $entry.data.title %}
+```
+
+The `$entry` object matches [the `CollectionEntry` type](https://docs.astro.build/en/reference/api-reference/#collection-entry-type), excluding the `.render()` property.
+
 ### Markdoc config
 
 The Markdoc integration accepts [all Markdoc configuration options](https://markdoc.dev/docs/config), including [tags](https://markdoc.dev/docs/tags) and [functions](https://markdoc.dev/docs/functions).
@@ -292,11 +306,11 @@ You will need to install the `@markdoc/markdoc` package into your project first:
 
 ```sh
 # Using NPM
-npx astro add @markdoc/markdoc
+npm install @markdoc/markdoc
 # Using Yarn
-yarn astro add @markdoc/markdoc
+yarn add @markdoc/markdoc
 # Using PNPM
-pnpm astro add @markdoc/markdoc
+pnpm add @markdoc/markdoc
 ```
 
 Now, you can define Markdoc configuration options using `Markdock.transform()`.

package/components/Renderer.astro

@@ -2,8 +2,7 @@
 import type { RenderableTreeNode } from '@markdoc/markdoc';
 import type { AstroInstance } from 'astro';
 import { validateComponentsProp } from '../dist/utils.js';
-import { createAstroNode } from './astroNode';
-import RenderNode from './RenderNode.astro';
+import { ComponentNode, createTreeNode } from './TreeNode.js';
 
 type Props = {
 	content: RenderableTreeNode;
@@ -18,4 +17,4 @@ if (components) {
 }
 ---
 
-<RenderNode node={createAstroNode(content, components)} />
+<ComponentNode treeNode={createTreeNode(content, components)} />

package/components/TreeNode.ts

@@ -0,0 +1,90 @@
+import type { AstroInstance } from 'astro';
+import type { RenderableTreeNode } from '@markdoc/markdoc';
+import { createComponent, renderComponent, render } from 'astro/runtime/server/index.js';
+// @ts-expect-error Cannot find module 'astro:markdoc-assets' or its corresponding type declarations
+import { Image } from 'astro:markdoc-assets';
+import Markdoc from '@markdoc/markdoc';
+import { MarkdocError, isCapitalized } from '../dist/utils.js';
+
+export type TreeNode =
+	| {
+			type: 'text';
+			content: string;
+	  }
+	| {
+			type: 'component';
+			component: AstroInstance['default'];
+			props: Record<string, any>;
+			children: TreeNode[];
+	  }
+	| {
+			type: 'element';
+			tag: string;
+			attributes: Record<string, any>;
+			children: TreeNode[];
+	  };
+
+export const ComponentNode = createComponent({
+	factory(result: any, { treeNode }: { treeNode: TreeNode }) {
+		if (treeNode.type === 'text') return render`${treeNode.content}`;
+		const slots = {
+			default: () =>
+				render`${treeNode.children.map((child) =>
+					renderComponent(result, 'ComponentNode', ComponentNode, { treeNode: child })
+				)}`,
+		};
+		if (treeNode.type === 'component') {
+			return renderComponent(
+				result,
+				treeNode.component.name,
+				treeNode.component,
+				treeNode.props,
+				slots
+			);
+		}
+		return renderComponent(result, treeNode.tag, treeNode.tag, treeNode.attributes, slots);
+	},
+	propagation: 'none',
+});
+
+const builtInComponents: Record<string, AstroInstance['default']> = {
+	Image,
+};
+
+export function createTreeNode(
+	node: RenderableTreeNode,
+	userComponents: Record<string, AstroInstance['default']> = {}
+): TreeNode {
+	const components = { ...userComponents, ...builtInComponents };
+
+	if (typeof node === 'string' || typeof node === 'number') {
+		return { type: 'text', content: String(node) };
+	} else if (node === null || typeof node !== 'object' || !Markdoc.Tag.isTag(node)) {
+		return { type: 'text', content: '' };
+	}
+
+	if (node.name in components) {
+		const component = components[node.name];
+		const props = node.attributes;
+		const children = node.children.map((child) => createTreeNode(child, components));
+
+		return {
+			type: 'component',
+			component,
+			props,
+			children,
+		};
+	} else if (isCapitalized(node.name)) {
+		throw new MarkdocError({
+			message: `Unable to render ${JSON.stringify(node.name)}.`,
+			hint: 'Did you add this to the "components" prop on your <Content /> component?',
+		});
+	} else {
+		return {
+			type: 'element',
+			tag: node.name,
+			attributes: node.attributes,
+			children: node.children.map((child) => createTreeNode(child, components)),
+		};
+	}
+}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import type { Config } from '@markdoc/markdoc';
+import type { Config as ReadonlyMarkdocConfig } from '@markdoc/markdoc';
 import type { AstroIntegration } from 'astro';
-export default function markdoc(markdocConfig?: Config): AstroIntegration;
+export default function markdocIntegration(userMarkdocConfig?: ReadonlyMarkdocConfig): AstroIntegration;

package/dist/index.js

@@ -3,16 +3,27 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import {
   getAstroConfigPath,
+  isValidUrl,
   MarkdocError,
   parseFrontmatter,
   prependForwardSlash
 } from "./utils.js";
-function markdoc(markdocConfig = {}) {
+import { emitESMImage } from "astro/assets";
+function markdocIntegration(userMarkdocConfig = {}) {
   return {
     name: "@astrojs/markdoc",
     hooks: {
       "astro:config:setup": async (params) => {
-        const { updateConfig, config, addContentEntryType } = params;
+        const {
+          updateConfig,
+          config: astroConfig,
+          addContentEntryType
+        } = params;
+        updateConfig({
+          vite: {
+            plugins: [safeAssetsVirtualModulePlugin({ astroConfig })]
+          }
+        });
         function getEntryInfo({ fileUrl, contents }) {
           const parsed = parseFrontmatter(contents, fileURLToPath(fileUrl));
           return {
@@ -25,42 +36,85 @@ function markdoc(markdocConfig = {}) {
         addContentEntryType({
           extensions: [".mdoc"],
           getEntryInfo,
+          async getRenderModule({ entry }) {
+            var _a;
+            validateRenderProperties(userMarkdocConfig, astroConfig);
+            const ast = Markdoc.parse(entry.body);
+            const pluginContext = this;
+            const markdocConfig = {
+              ...userMarkdocConfig,
+              variables: {
+                ...userMarkdocConfig.variables,
+                entry
+              }
+            };
+            if ((_a = astroConfig.experimental) == null ? void 0 : _a.assets) {
+              await emitOptimizedImages(ast.children, {
+                astroConfig,
+                pluginContext,
+                filePath: entry._internal.filePath
+              });
+              markdocConfig.nodes ??= {};
+              markdocConfig.nodes.image = {
+                ...Markdoc.nodes.image,
+                transform(node, config) {
+                  const attributes = node.transformAttributes(config);
+                  const children = node.transformChildren(config);
+                  if (node.type === "image" && "__optimizedSrc" in node.attributes) {
+                    const { __optimizedSrc, ...rest } = node.attributes;
+                    return new Markdoc.Tag("Image", { ...rest, src: __optimizedSrc }, children);
+                  } else {
+                    return new Markdoc.Tag("img", attributes, children);
+                  }
+                }
+              };
+            }
+            const content = Markdoc.transform(ast, markdocConfig);
+            return {
+              code: `import { jsx as h } from 'astro/jsx-runtime';
+import { Renderer } from '@astrojs/markdoc/components';
+const transformedContent = ${JSON.stringify(
+                content
+              )};
+export async function Content ({ components }) { return h(Renderer, { content: transformedContent, components }); }
+Content[Symbol.for('astro.needsHeadRendering')] = true;`
+            };
+          },
           contentModuleTypes: await fs.promises.readFile(
             new URL("../template/content-module-types.d.ts", import.meta.url),
             "utf-8"
           )
         });
-        const viteConfig = {
-          plugins: [
-            {
-              name: "@astrojs/markdoc",
-              async transform(code, id) {
-                if (!id.endsWith(".mdoc"))
-                  return;
-                validateRenderProperties(markdocConfig, config);
-                const body = getEntryInfo({
-                  // Can't use `pathToFileUrl` - Vite IDs are not plain file paths
-                  fileUrl: new URL(prependForwardSlash(id), "file://"),
-                  contents: code
-                }).body;
-                const ast = Markdoc.parse(body);
-                const content = Markdoc.transform(ast, markdocConfig);
-                return `import { jsx as h } from 'astro/jsx-runtime';
-import { Renderer } from '@astrojs/markdoc/components';
-const transformedContent = ${JSON.stringify(
-                  content
-                )};
-export async function Content ({ components }) { return h(Renderer, { content: transformedContent, components }); }
-Content[Symbol.for('astro.needsHeadRendering')] = true;`;
-              }
-            }
-          ]
-        };
-        updateConfig({ vite: viteConfig });
       }
     }
   };
 }
+async function emitOptimizedImages(nodeChildren, ctx) {
+  for (const node of nodeChildren) {
+    if (node.type === "image" && typeof node.attributes.src === "string" && shouldOptimizeImage(node.attributes.src)) {
+      const resolved = await ctx.pluginContext.resolve(node.attributes.src, ctx.filePath);
+      if ((resolved == null ? void 0 : resolved.id) && fs.existsSync(new URL(prependForwardSlash(resolved.id), "file://"))) {
+        const src = await emitESMImage(
+          resolved.id,
+          ctx.pluginContext.meta.watchMode,
+          ctx.pluginContext.emitFile,
+          { config: ctx.astroConfig }
+        );
+        node.attributes.__optimizedSrc = src;
+      } else {
+        throw new MarkdocError({
+          message: `Could not resolve image ${JSON.stringify(
+            node.attributes.src
+          )} from ${JSON.stringify(ctx.filePath)}. Does the file exist?`
+        });
+      }
+    }
+    await emitOptimizedImages(node.children, ctx);
+  }
+}
+function shouldOptimizeImage(src) {
+  return !isValidUrl(src) && !src.startsWith("/");
+}
 function validateRenderProperties(markdocConfig, astroConfig) {
   const tags = markdocConfig.tags ?? {};
   const nodes = markdocConfig.nodes ?? {};
@@ -100,6 +154,30 @@ function validateRenderProperty({
 function isCapitalized(str) {
   return str.length > 0 && str[0] === str[0].toUpperCase();
 }
+function safeAssetsVirtualModulePlugin({
+  astroConfig
+}) {
+  const virtualModuleId = "astro:markdoc-assets";
+  const resolvedVirtualModuleId = "\0" + virtualModuleId;
+  return {
+    name: "astro:markdoc-safe-assets-virtual-module",
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    load(id) {
+      var _a;
+      if (id !== resolvedVirtualModuleId)
+        return;
+      if ((_a = astroConfig.experimental) == null ? void 0 : _a.assets) {
+        return `export { Image } from 'astro:assets';`;
+      } else {
+        return `export const Image = () => { throw new Error('Cannot use the Image component without the \`experimental.assets\` flag.'); }`;
+      }
+    }
+  };
+}
 export {
-  markdoc as default
+  markdocIntegration as default
 };

package/dist/utils.d.ts

@@ -47,4 +47,5 @@ export declare function getAstroConfigPath(fs: typeof fsMod, root: string): stri
 export declare function prependForwardSlash(str: string): string;
 export declare function validateComponentsProp(components: Record<string, AstroInstance['default']>): void;
 export declare function isCapitalized(str: string): boolean;
+export declare function isValidUrl(str: string): boolean;
 export {};

package/dist/utils.js

@@ -84,10 +84,19 @@ const componentsPropValidator = z.record(
 function isCapitalized(str) {
   return str.length > 0 && str[0] === str[0].toUpperCase();
 }
+function isValidUrl(str) {
+  try {
+    new URL(str);
+    return true;
+  } catch {
+    return false;
+  }
+}
 export {
   MarkdocError,
   getAstroConfigPath,
   isCapitalized,
+  isValidUrl,
   parseFrontmatter,
   prependForwardSlash,
   validateComponentsProp

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrojs/markdoc",
   "description": "Add support for Markdoc pages in your Astro site",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "types": "./dist/index.d.ts",
   "author": "withastro",
@@ -26,19 +26,22 @@
   "dependencies": {
     "@markdoc/markdoc": "^0.2.2",
     "gray-matter": "^4.0.3",
-    "stringify-attributes": "^3.0.0",
     "zod": "^3.17.3"
   },
+  "peerDependencies": {
+    "astro": "2.1.7"
+  },
   "devDependencies": {
+    "astro": "2.1.7",
     "@types/chai": "^4.3.1",
     "@types/html-escaper": "^3.0.0",
     "@types/mocha": "^9.1.1",
-    "astro": "2.1.4",
     "astro-scripts": "0.0.14",
     "chai": "^4.3.6",
     "devalue": "^4.2.0",
     "linkedom": "^0.14.12",
     "mocha": "^9.2.2",
+    "rollup": "^3.20.1",
     "vite": "^4.0.3"
   },
   "engines": {

package/src/index.ts

@@ -1,15 +1,23 @@
-import type { Config } from '@markdoc/markdoc';
+import type {
+	Config as ReadonlyMarkdocConfig,
+	ConfigType as MarkdocConfig,
+	Node,
+} from '@markdoc/markdoc';
 import Markdoc from '@markdoc/markdoc';
 import type { AstroConfig, AstroIntegration, ContentEntryType, HookParameters } from 'astro';
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import type { InlineConfig } from 'vite';
+import type * as rollup from 'rollup';
 import {
 	getAstroConfigPath,
+	isValidUrl,
 	MarkdocError,
 	parseFrontmatter,
 	prependForwardSlash,
 } from './utils.js';
+// @ts-expect-error Cannot find module 'astro/assets' or its corresponding type declarations.
+import { emitESMImage } from 'astro/assets';
+import type { Plugin as VitePlugin } from 'vite';
 
 type SetupHookParams = HookParameters<'astro:config:setup'> & {
 	// `contentEntryType` is not a public API
@@ -17,12 +25,24 @@ type SetupHookParams = HookParameters<'astro:config:setup'> & {
 	addContentEntryType: (contentEntryType: ContentEntryType) => void;
 };
 
-export default function markdoc(markdocConfig: Config = {}): AstroIntegration {
+export default function markdocIntegration(
+	userMarkdocConfig: ReadonlyMarkdocConfig = {}
+): AstroIntegration {
 	return {
 		name: '@astrojs/markdoc',
 		hooks: {
 			'astro:config:setup': async (params) => {
-				const { updateConfig, config, addContentEntryType } = params as SetupHookParams;
+				const {
+					updateConfig,
+					config: astroConfig,
+					addContentEntryType,
+				} = params as SetupHookParams;
+
+				updateConfig({
+					vite: {
+						plugins: [safeAssetsVirtualModulePlugin({ astroConfig })],
+					},
+				});
 
 				function getEntryInfo({ fileUrl, contents }: { fileUrl: URL; contents: string }) {
 					const parsed = parseFrontmatter(contents, fileURLToPath(fileUrl));
@@ -36,42 +56,108 @@ export default function markdoc(markdocConfig: Config = {}): AstroIntegration {
 				addContentEntryType({
 					extensions: ['.mdoc'],
 					getEntryInfo,
+					async getRenderModule({ entry }) {
+						validateRenderProperties(userMarkdocConfig, astroConfig);
+						const ast = Markdoc.parse(entry.body);
+						const pluginContext = this;
+						const markdocConfig: MarkdocConfig = {
+							...userMarkdocConfig,
+							variables: {
+								...userMarkdocConfig.variables,
+								entry,
+							},
+						};
+
+						if (astroConfig.experimental?.assets) {
+							await emitOptimizedImages(ast.children, {
+								astroConfig,
+								pluginContext,
+								filePath: entry._internal.filePath,
+							});
+
+							markdocConfig.nodes ??= {};
+							markdocConfig.nodes.image = {
+								...Markdoc.nodes.image,
+								transform(node, config) {
+									const attributes = node.transformAttributes(config);
+									const children = node.transformChildren(config);
+
+									if (node.type === 'image' && '__optimizedSrc' in node.attributes) {
+										const { __optimizedSrc, ...rest } = node.attributes;
+										return new Markdoc.Tag('Image', { ...rest, src: __optimizedSrc }, children);
+									} else {
+										return new Markdoc.Tag('img', attributes, children);
+									}
+								},
+							};
+						}
+
+						const content = Markdoc.transform(ast, markdocConfig);
+
+						return {
+							code: `import { jsx as h } from 'astro/jsx-runtime';\nimport { Renderer } from '@astrojs/markdoc/components';\nconst transformedContent = ${JSON.stringify(
+								content
+							)};\nexport async function Content ({ components }) { return h(Renderer, { content: transformedContent, components }); }\nContent[Symbol.for('astro.needsHeadRendering')] = true;`,
+						};
+					},
 					contentModuleTypes: await fs.promises.readFile(
 						new URL('../template/content-module-types.d.ts', import.meta.url),
 						'utf-8'
 					),
 				});
-
-				const viteConfig: InlineConfig = {
-					plugins: [
-						{
-							name: '@astrojs/markdoc',
-							async transform(code, id) {
-								if (!id.endsWith('.mdoc')) return;
-
-								validateRenderProperties(markdocConfig, config);
-								const body = getEntryInfo({
-									// Can't use `pathToFileUrl` - Vite IDs are not plain file paths
-									fileUrl: new URL(prependForwardSlash(id), 'file://'),
-									contents: code,
-								}).body;
-								const ast = Markdoc.parse(body);
-								const content = Markdoc.transform(ast, markdocConfig);
-
-								return `import { jsx as h } from 'astro/jsx-runtime';\nimport { Renderer } from '@astrojs/markdoc/components';\nconst transformedContent = ${JSON.stringify(
-									content
-								)};\nexport async function Content ({ components }) { return h(Renderer, { content: transformedContent, components }); }\nContent[Symbol.for('astro.needsHeadRendering')] = true;`;
-							},
-						},
-					],
-				};
-				updateConfig({ vite: viteConfig });
 			},
 		},
 	};
 }
 
-function validateRenderProperties(markdocConfig: Config, astroConfig: AstroConfig) {
+/**
+ * Emits optimized images, and appends the generated `src` to each AST node
+ * via the `__optimizedSrc` attribute.
+ */
+async function emitOptimizedImages(
+	nodeChildren: Node[],
+	ctx: {
+		pluginContext: rollup.PluginContext;
+		filePath: string;
+		astroConfig: AstroConfig;
+	}
+) {
+	for (const node of nodeChildren) {
+		if (
+			node.type === 'image' &&
+			typeof node.attributes.src === 'string' &&
+			shouldOptimizeImage(node.attributes.src)
+		) {
+			// Attempt to resolve source with Vite.
+			// This handles relative paths and configured aliases
+			const resolved = await ctx.pluginContext.resolve(node.attributes.src, ctx.filePath);
+
+			if (resolved?.id && fs.existsSync(new URL(prependForwardSlash(resolved.id), 'file://'))) {
+				const src = await emitESMImage(
+					resolved.id,
+					ctx.pluginContext.meta.watchMode,
+					ctx.pluginContext.emitFile,
+					{ config: ctx.astroConfig }
+				);
+				node.attributes.__optimizedSrc = src;
+			} else {
+				throw new MarkdocError({
+					message: `Could not resolve image ${JSON.stringify(
+						node.attributes.src
+					)} from ${JSON.stringify(ctx.filePath)}. Does the file exist?`,
+				});
+			}
+		}
+		await emitOptimizedImages(node.children, ctx);
+	}
+}
+
+function shouldOptimizeImage(src: string) {
+	// Optimize anything that is NOT external or an absolute path to `public/`
+	return !isValidUrl(src) && !src.startsWith('/');
+}
+
+function validateRenderProperties(markdocConfig: ReadonlyMarkdocConfig, astroConfig: AstroConfig) {
 	const tags = markdocConfig.tags ?? {};
 	const nodes = markdocConfig.nodes ?? {};
 
@@ -120,3 +206,37 @@ function validateRenderProperty({
 function isCapitalized(str: string) {
 	return str.length > 0 && str[0] === str[0].toUpperCase();
 }
+
+/**
+ * TODO: remove when `experimental.assets` is baselined.
+ *
+ * `astro:assets` will fail to resolve if the `experimental.assets` flag is not enabled.
+ * This ensures a fallback for the Markdoc renderer to safely import at the top level.
+ * @see ../components/TreeNode.ts
+ */
+function safeAssetsVirtualModulePlugin({
+	astroConfig,
+}: {
+	astroConfig: Pick<AstroConfig, 'experimental'>;
+}): VitePlugin {
+	const virtualModuleId = 'astro:markdoc-assets';
+	const resolvedVirtualModuleId = '\0' + virtualModuleId;
+
+	return {
+		name: 'astro:markdoc-safe-assets-virtual-module',
+		resolveId(id) {
+			if (id === virtualModuleId) {
+				return resolvedVirtualModuleId;
+			}
+		},
+		load(id) {
+			if (id !== resolvedVirtualModuleId) return;
+
+			if (astroConfig.experimental?.assets) {
+				return `export { Image } from 'astro:assets';`;
+			} else {
+				return `export const Image = () => { throw new Error('Cannot use the Image component without the \`experimental.assets\` flag.'); }`;
+			}
+		},
+	};
+}

package/src/utils.ts

@@ -145,3 +145,12 @@ const componentsPropValidator = z.record(
 export function isCapitalized(str: string) {
 	return str.length > 0 && str[0] === str[0].toUpperCase();
 }
+
+export function isValidUrl(str: string): boolean {
+	try {
+		new URL(str);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/test/entry-prop.test.js

@@ -0,0 +1,58 @@
+import { parseHTML } from 'linkedom';
+import { expect } from 'chai';
+import { loadFixture } from '../../../astro/test/test-utils.js';
+import markdoc from '../dist/index.js';
+
+const root = new URL('./fixtures/entry-prop/', import.meta.url);
+
+describe('Markdoc - Entry prop', () => {
+	let baseFixture;
+
+	before(async () => {
+		baseFixture = await loadFixture({
+			root,
+			integrations: [markdoc()],
+		});
+	});
+
+	describe('dev', () => {
+		let devServer;
+
+		before(async () => {
+			devServer = await baseFixture.startDevServer();
+		});
+
+		after(async () => {
+			await devServer.stop();
+		});
+
+		it('has expected entry properties', async () => {
+			const res = await baseFixture.fetch('/');
+			const html = await res.text();
+			const { document } = parseHTML(html);
+			expect(document.querySelector('h1')?.textContent).to.equal('Processed by schema: Test entry');
+			expect(document.getElementById('id')?.textContent?.trim()).to.equal('id: entry.mdoc');
+			expect(document.getElementById('slug')?.textContent?.trim()).to.equal('slug: entry');
+			expect(document.getElementById('collection')?.textContent?.trim()).to.equal(
+				'collection: blog'
+			);
+		});
+	});
+
+	describe('build', () => {
+		before(async () => {
+			await baseFixture.build();
+		});
+
+		it('has expected entry properties', async () => {
+			const html = await baseFixture.readFile('/index.html');
+			const { document } = parseHTML(html);
+			expect(document.querySelector('h1')?.textContent).to.equal('Processed by schema: Test entry');
+			expect(document.getElementById('id')?.textContent?.trim()).to.equal('id: entry.mdoc');
+			expect(document.getElementById('slug')?.textContent?.trim()).to.equal('slug: entry');
+			expect(document.getElementById('collection')?.textContent?.trim()).to.equal(
+				'collection: blog'
+			);
+		});
+	});
+});

package/test/fixtures/entry-prop/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()],
+});

package/test/fixtures/entry-prop/node_modules/.bin/astro

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/astro/astro/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="$NODE_PATH:/home/runner/work/astro/astro/node_modules/.pnpm/node_modules"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../../../../astro/astro.js" "$@"
+else
+  exec node  "$basedir/../../../../../../../astro/astro.js" "$@"
+fi

package/test/fixtures/entry-prop/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@test/markdoc-entry-prop",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "@astrojs/markdoc": "workspace:*",
+    "astro": "workspace:*"
+  }
+}

package/test/fixtures/entry-prop/src/content/blog/entry.mdoc

@@ -0,0 +1,9 @@
+---
+title: Test entry
+---
+
+# {% $entry.data.title %}
+
+- id: {% $entry.id %} {% #id %}
+- slug: {% $entry.slug %} {% #slug %}
+- collection: {% $entry.collection %} {% #collection %}

package/test/fixtures/entry-prop/src/content/config.ts

@@ -0,0 +1,9 @@
+import { defineCollection, z } from 'astro:content';
+
+const blog = defineCollection({
+	schema: z.object({
+		title: z.string().transform(v => 'Processed by schema: ' + v),
+	}),
+});
+
+export const collections = { blog }

package/test/fixtures/entry-prop/src/pages/index.astro

@@ -0,0 +1,19 @@
+---
+import { getEntryBySlug } from 'astro:content';
+
+const entry = await getEntryBySlug('blog', 'entry');
+const { Content } = await entry.render();
+---
+
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<meta name="viewport" content="width=device-width" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Astro</title>
+	</head>
+	<body>
+		<Content />
+	</body>
+</html>

package/test/fixtures/image-assets/astro.config.mjs

@@ -0,0 +1,10 @@
+import { defineConfig } from 'astro/config';
+import markdoc from '@astrojs/markdoc';
+
+// https://astro.build/config
+export default defineConfig({
+	experimental: {
+		assets: true,
+	},
+	integrations: [markdoc()],
+});

package/test/fixtures/image-assets/node_modules/.bin/astro

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/astro/astro/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="$NODE_PATH:/home/runner/work/astro/astro/node_modules/.pnpm/node_modules"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../../../../astro/astro.js" "$@"
+else
+  exec node  "$basedir/../../../../../../../astro/astro.js" "$@"
+fi

package/test/fixtures/image-assets/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@test/image-assets",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "@astrojs/markdoc": "workspace:*",
+    "astro": "workspace:*"
+  }
+}

package/test/fixtures/image-assets/src/content/docs/intro.mdoc

@@ -0,0 +1,7 @@
+# Image assets
+
+![Favicon](/favicon.svg) {% #public %}
+
+![Oar](../../assets/relative/oar.jpg) {% #relative %}
+
+![Gray cityscape arial view](~/assets/alias/cityscape.jpg) {% #alias %}

package/test/fixtures/image-assets/src/pages/index.astro

@@ -0,0 +1,19 @@
+---
+import { getEntryBySlug } from 'astro:content';
+
+const intro = await getEntryBySlug('docs', 'intro');
+const { Content } = await intro.render();
+---
+
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<meta name="viewport" content="width=device-width" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Astro</title>
+	</head>
+	<body>
+		<Content />
+	</body>
+</html>

package/test/fixtures/image-assets/src/public/favicon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 128 128">
+    <path d="M50.4 78.5a75.1 75.1 0 0 0-28.5 6.9l24.2-65.7c.7-2 1.9-3.2 3.4-3.2h29c1.5 0 2.7 1.2 3.4 3.2l24.2 65.7s-11.6-7-28.5-7L67 45.5c-.4-1.7-1.6-2.8-2.9-2.8-1.3 0-2.5 1.1-2.9 2.7L50.4 78.5Zm-1.1 28.2Zm-4.2-20.2c-2 6.6-.6 15.8 4.2 20.2a17.5 17.5 0 0 1 .2-.7 5.5 5.5 0 0 1 5.7-4.5c2.8.1 4.3 1.5 4.7 4.7.2 1.1.2 2.3.2 3.5v.4c0 2.7.7 5.2 2.2 7.4a13 13 0 0 0 5.7 4.9v-.3l-.2-.3c-1.8-5.6-.5-9.5 4.4-12.8l1.5-1a73 73 0 0 0 3.2-2.2 16 16 0 0 0 6.8-11.4c.3-2 .1-4-.6-6l-.8.6-1.6 1a37 37 0 0 1-22.4 2.7c-5-.7-9.7-2-13.2-6.2Z" />
+    <style>
+        path { fill: #000; }
+        @media (prefers-color-scheme: dark) {
+            path { fill: #FFF; }
+        }
+    </style>
+</svg>

package/test/image-assets.test.js

@@ -0,0 +1,76 @@
+import { parseHTML } from 'linkedom';
+import { expect } from 'chai';
+import { loadFixture } from '../../../astro/test/test-utils.js';
+
+const root = new URL('./fixtures/image-assets/', import.meta.url);
+
+describe('Markdoc - Image assets', () => {
+	let baseFixture;
+
+	before(async () => {
+		baseFixture = await loadFixture({
+			root,
+		});
+	});
+
+	describe('dev', () => {
+		let devServer;
+
+		before(async () => {
+			devServer = await baseFixture.startDevServer();
+		});
+
+		after(async () => {
+			await devServer.stop();
+		});
+
+		it('uses public/ image paths unchanged', async () => {
+			const res = await baseFixture.fetch('/');
+			const html = await res.text();
+			const { document } = parseHTML(html);
+			expect(document.querySelector('#public > img')?.src).to.equal('/favicon.svg');
+		});
+
+		it('transforms relative image paths to optimized path', async () => {
+			const res = await baseFixture.fetch('/');
+			const html = await res.text();
+			const { document } = parseHTML(html);
+			expect(document.querySelector('#relative > img')?.src).to.equal(
+				'/_image?href=%2Fsrc%2Fassets%2Frelative%2Foar.jpg%3ForigWidth%3D420%26origHeight%3D630%26origFormat%3Djpg&f=webp'
+			);
+		});
+
+		it('transforms aliased image paths to optimized path', async () => {
+			const res = await baseFixture.fetch('/');
+			const html = await res.text();
+			const { document } = parseHTML(html);
+			expect(document.querySelector('#alias > img')?.src).to.equal(
+				'/_image?href=%2Fsrc%2Fassets%2Falias%2Fcityscape.jpg%3ForigWidth%3D420%26origHeight%3D280%26origFormat%3Djpg&f=webp'
+			);
+		});
+	});
+
+	describe('build', () => {
+		before(async () => {
+			await baseFixture.build();
+		});
+
+		it('uses public/ image paths unchanged', async () => {
+			const html = await baseFixture.readFile('/index.html');
+			const { document } = parseHTML(html);
+			expect(document.querySelector('#public > img')?.src).to.equal('/favicon.svg');
+		});
+
+		it('transforms relative image paths to optimized path', async () => {
+			const html = await baseFixture.readFile('/index.html');
+			const { document } = parseHTML(html);
+			expect(document.querySelector('#relative > img')?.src).to.match(/^\/_astro\/oar.*\.webp$/);
+		});
+
+		it('transforms aliased image paths to optimized path', async () => {
+			const html = await baseFixture.readFile('/index.html');
+			const { document } = parseHTML(html);
+			expect(document.querySelector('#alias > img')?.src).to.match(/^\/_astro\/cityscape.*\.webp$/);
+		});
+	});
+});

package/components/RenderNode.astro

@@ -1,30 +0,0 @@
----
-import stringifyAttributes from 'stringify-attributes';
-import type { AstroNode } from './astroNode';
-
-type Props = {
-	node: AstroNode;
-};
-
-const Node = (Astro.props as Props).node;
----
-
-{
-	typeof Node === 'string' ? (
-		<Fragment set:text={Node} />
-	) : 'component' in Node ? (
-		<Node.component {...Node.props}>
-			{Node.children.map((child) => (
-				<Astro.self node={child} />
-			))}
-		</Node.component>
-	) : (
-		<Fragment>
-			<Fragment set:html={`<${Node.tag} ${stringifyAttributes(Node.attributes)}>`} />
-			{Node.children.map((child) => (
-				<Astro.self node={child} />
-			))}
-			<Fragment set:html={`</${Node.tag}>`} />
-		</Fragment>
-	)
-}

package/components/astroNode.ts

@@ -1,51 +0,0 @@
-import type { AstroInstance } from 'astro';
-import type { RenderableTreeNode } from '@markdoc/markdoc';
-import Markdoc from '@markdoc/markdoc';
-import { MarkdocError, isCapitalized } from '../dist/utils.js';
-
-export type AstroNode =
-	| string
-	| {
-			component: AstroInstance['default'];
-			props: Record<string, any>;
-			children: AstroNode[];
-	  }
-	| {
-			tag: string;
-			attributes: Record<string, any>;
-			children: AstroNode[];
-	  };
-
-export function createAstroNode(
-	node: RenderableTreeNode,
-	components: Record<string, AstroInstance['default']> = {}
-): AstroNode {
-	if (typeof node === 'string' || typeof node === 'number') {
-		return String(node);
-	} else if (node === null || typeof node !== 'object' || !Markdoc.Tag.isTag(node)) {
-		return '';
-	}
-
-	if (node.name in components) {
-		const component = components[node.name];
-		const props = node.attributes;
-		const children = node.children.map((child) => createAstroNode(child, components));
-
-		return {
-			component,
-			props,
-			children,
-		};
-	} else if (isCapitalized(node.name)) {
-		throw new MarkdocError({
-			message: `Unable to render ${JSON.stringify(node.name)}.`,
-			hint: 'Did you add this to the "components" prop on your <Content /> component?',
-		});
-	} else {
-		return {
-			tag: node.name,
-			attributes: node.attributes,
-			children: node.children.map((child) => createAstroNode(child, components)),
-		};
-	}
-}