[Markdoc] New config format with runtime variable support! (#6653)

* deps: esbuild

* feat: support direct component imports for render!

* deps: add devalue back

* refactor: remove unused components prop

* refactor: load experimental assets config separately

* fix: upate Content type def to support props

* refactor: replace astro stub with inline data

* feat: pass through viteId to getRenderMod

* fix: add back $entry var with defaults convention

* chore: remove unneeded validateRenderProps

* chore: remove uneeded validateComponents

* fix: remove userMarkdocConfig prop

* chore: add helpful error for legacy config

* deps: kleur

* fix: add back `isCapitalized`

* fix: log instead of throw to avoid scary stacktrace

* chore: delete more old logic (nice)

* chore: delete MORE unused utils

* chore: comment on separate assets config

* chore: remove console.log

* chore: general code cleanup

* test: new render config

* docs: new README

* fix: add expect-error on astro:assets

* feat: add defineMarkdocConfig helper

* docs: update example README

* test: add runtime variable

* chore: lint

* chore: changeset

* chore: add component import deletion

* docs: add notes on Vite fork

* fix: astro check

* chore: add `.mts` to markdoc config formats

.changeset/metal-cameras-bow.md

@@ -0,0 +1,42 @@
+---
+'@astrojs/markdoc': minor
+'astro': patch
+---
+
+Simplify Markdoc configuration with a new `markdoc.config.mjs` file. This lets you import Astro components directly to render as Markdoc tags and nodes, without the need for the previous `components` property. This new configuration also unlocks passing variables to your Markdoc from the `Content` component ([see the new docs](https://docs.astro.build/en/guides/integrations-guide/markdoc/#pass-markdoc-variables)).
+
+## Migration
+
+Move any existing Markdoc config from your `astro.config` to a new `markdoc.config.mjs` file at the root of your project. This should be applied as a default export, with the optional `defineMarkdocConfig()` helper for autocomplete in your editor.
+
+This example configures an `aside` Markdoc tag. Note that components should be imported and applied to the `render` attribute _directly,_ instead of passing the name as a string:
+
+```js
+// markdoc.config.mjs
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import Aside from './src/components/Aside.astro';
+
+export default defineMarkdocConfig({
+  tags: {
+    aside: {
+      render: Aside,
+    }
+  }
+});
+```
+
+You should also remove the `components` prop from your `Content` components. Since components are imported into your config directly, this is no longer needed.
+
+```diff
+---
+- import Aside from '../components/Aside.astro';
+import { getEntryBySlug } from 'astro:content';
+
+const entry = await getEntryBySlug('docs', 'why-markdoc');
+const { Content } = await entry.render();
+---
+
+<Content
+- components={{ Aside }}
+/>
+```

examples/with-markdoc/README.md

@@ -23,23 +23,20 @@ Inside of your Astro project, you'll see the following folders and files:
         └── docs/
 │           └── intro.mdoc
 |       └── config.ts
-│   └── components/
-|       ├── Aside.astro
-│       └── DocsContent.astro
-│   └── layouts/
-│       └── Layout.astro
-│   └── pages/
-│       └── index.astro
+│   └── components/Aside.astro
+│   └── layouts/Layout.astro
+│   └── pages/index.astro
 |   └── env.d.ts
 ├── astro.config.mjs
+├── markdoc.config.mjs
 ├── README.md
 ├── package.json
 └── tsconfig.json
 ```
 
-Markdoc (`.mdoc`) files can be used in content collections to author your Markdown content alongside Astro and server-rendered UI framework components (React, Vue, Svelte, and more). See `src/content/docs/` for an example file.
+Markdoc (`.mdoc`) files can be used in content collections. See `src/content/docs/` for an example file.
 
-You can also apply Astro components and server-rendered UI components (React, Vue, Svelte, etc) to your Markdoc files. See `src/content/DocsContent.astro` for an example.
+You can also render Astro components from your Markdoc files using [tags](https://markdoc.dev/docs/tags). See the `markdoc.config.mjs` file for an example configuration.
 
 ## 🧞 Commands
 

examples/with-markdoc/astro.config.mjs

@@ -3,17 +3,5 @@ import markdoc from '@astrojs/markdoc';
 
 // https://astro.build/config
 export default defineConfig({
-	integrations: [
-		markdoc({
-			tags: {
-				aside: {
-					render: 'Aside',
-					attributes: {
-						type: { type: String },
-						title: { type: String },
-					},
-				},
-			},
-		}),
-	],
+	integrations: [markdoc()],
 });

examples/with-markdoc/markdoc.config.mjs

@@ -0,0 +1,14 @@
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import Aside from './src/components/Aside.astro';
+
+export default defineMarkdocConfig({
+	tags: {
+		aside: {
+			render: Aside,
+			attributes: {
+				type: { type: String },
+				title: { type: String },
+			},
+		},
+	},
+});

examples/with-markdoc/package.json

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@astrojs/markdoc": "^0.0.5",
-    "astro": "^2.1.7"
+    "astro": "^2.1.7",
+    "kleur": "^4.1.5"
   }
 }

examples/with-markdoc/src/pages/index.astro

@@ -1,18 +1,25 @@
 ---
 import { getEntryBySlug } from 'astro:content';
-import DocsContent from '../components/DocsContent.astro';
 import Layout from '../layouts/Layout.astro';
 
 const intro = await getEntryBySlug('docs', 'intro');
+const { Content } = await intro.render();
 ---
 
 <Layout title={intro.data.title}>
 	<main>
 		<h1>{intro.data.title}</h1>
-		<!-- `DocsContent` is a thin wrapper around -->
-		<!-- the `Content` component provided by Content Collections, -->
-		<!-- with added configuration for components. -->
-		<!-- This allows you to share global components wherever you render your Markdoc. -->
-		<DocsContent entry={intro} />
+		<Content variables={{ revealSecret: true }} />
 	</main>
 </Layout>
+
+<style is:global>
+	table {
+		margin-block: 2rem;
+		margin-inline: auto;
+	}
+	table td {
+		padding-block: 0.3rem;
+		padding-inline: 0.5rem;
+	}
+</style>

packages/astro/src/@types/astro.ts

@@ -1056,6 +1056,7 @@ export interface ContentEntryType {
 	getRenderModule?(
 		this: rollup.PluginContext,
 		params: {
+			viteId: string;
 			entry: ContentEntryModule;
 		}
 	): rollup.LoadResult | Promise<rollup.LoadResult>;

packages/astro/src/content/vite-plugin-content-imports.ts

@@ -139,7 +139,7 @@ export const _internal = {
 					});
 				}
 
-				return contentRenderer.bind(this)({ entry });
+				return contentRenderer.bind(this)({ entry, viteId });
 			},
 		});
 	}