@astrojs/markdoc 0.0.4 → 0.1.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
-@astrojs/markdoc:build: cache hit, replaying output a6e7d1873a50f12c
-@astrojs/markdoc:build: 
-@astrojs/markdoc:build: > @astrojs/markdoc@0.0.4 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 821991cc611aa46c
+@astrojs/markdoc:build: 
+@astrojs/markdoc:build: > @astrojs/markdoc@0.1.0 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,71 @@
 # @astrojs/markdoc
 
+## 0.1.0
+
+### Minor Changes
+
+- [#6653](https://github.com/withastro/astro/pull/6653) [`7c439868a`](https://github.com/withastro/astro/commit/7c439868a3bc7d466418da9af669966014f3d9fe) Thanks [@bholmesdev](https://github.com/bholmesdev)! - 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 }}
+  />
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`1f783e320`](https://github.com/withastro/astro/commit/1f783e32075c20b13063599696644f5d47b75d8d), [`2e92e9aa9`](https://github.com/withastro/astro/commit/2e92e9aa976735c3ddb647152bb9c4850136e386), [`adecda7d6`](https://github.com/withastro/astro/commit/adecda7d6009793c5d20519a997e3b7afb08ad57), [`386336441`](https://github.com/withastro/astro/commit/386336441ad70017eea22db0683591126131db21), [`7c439868a`](https://github.com/withastro/astro/commit/7c439868a3bc7d466418da9af669966014f3d9fe), [`25cd3e574`](https://github.com/withastro/astro/commit/25cd3e574999c1c7294a089ad8c39df27ccdbf17), [`4bf87c64f`](https://github.com/withastro/astro/commit/4bf87c64ff7e9ca49e0f5c27e06bd49faaf60542), [`fc0ed9c53`](https://github.com/withastro/astro/commit/fc0ed9c53cd374860bbdb2503318a55ca09a2662)]:
+  - astro@2.1.8
+
+## 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

package/README.md

@@ -99,53 +99,46 @@ const { Content } = await entry.render();
 
 ### Using components
 
-You can add Astro and UI framework components (React, Vue, Svelte, etc.) to your Markdoc using both [Markdoc tags][markdoc-tags] and HTML element [nodes][markdoc-nodes].
+You can add Astro components to your Markdoc using both [Markdoc tags][markdoc-tags] and HTML element [nodes][markdoc-nodes].
 
 #### Render Markdoc tags as Astro components
 
-You may configure [Markdoc tags][markdoc-tags] that map to components. You can configure a new tag from your `astro.config` using the `tags` attribute.
+You may configure [Markdoc tags][markdoc-tags] that map to components. You can configure a new tag by creating a `markdoc.config.mjs|ts` file at the root of your project and configuring the `tag` attribute.
 
+This example renders an `Aside` component, and allows a `type` prop to be passed as a string:
 
 ```js
-// astro.config.mjs
-import { defineConfig } from 'astro/config';
-import markdoc from '@astrojs/markdoc';
-
-// https://astro.build/config
-export default defineConfig({
-  integrations: [
-    markdoc({
-      tags: {
-        aside: {
-          render: 'Aside',
-          attributes: {
-            // Component props as attribute definitions
-            // See Markdoc's documentation on defining attributes
-            // https://markdoc.dev/docs/attributes#defining-attributes
-            type: { type: String },
-          }
-        },
-      },
-    }),
-  ],
-});
+// markdoc.config.mjs
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import Aside from './src/components/Aside.astro';
+
+export default defineMarkdocConfig({
+  tags: {
+    aside: {
+      render: Aside,
+      attributes: {
+      // Markdoc requires type defs for each attribute.
+      // These should mirror the `Props` type of the component
+      // you are rendering. 
+      // See Markdoc's documentation on defining attributes
+      // https://markdoc.dev/docs/attributes#defining-attributes
+        type: { type: String },
+      }
+    },
+  },
+})
 ```
 
-Then, you can wire this render name (`'Aside'`) to a component from the `components` prop via the `<Content />` component. Note the object key name (`Aside` in this case) should match the render name:
+This component can now be used in your Markdoc files with the `{% aside %}` tag. Children will be passed to your component's default slot:
 
+```md
+# Welcome to Markdoc 👋
 
-```astro
----
-import { getEntryBySlug } from 'astro:content';
-import Aside from '../components/Aside.astro';
+{% aside type="tip" %}
 
-const entry = await getEntryBySlug('docs', 'why-markdoc');
-const { Content } = await entry.render();
----
+Use tags like this fancy "aside" to add some *flair* to your docs.
 
-<Content
-  components={{ Aside }}
-/>
+{% /aside %}
 ```
 
 #### Render Markdoc nodes / HTML elements as Astro components
@@ -153,46 +146,22 @@ const { Content } = await entry.render();
 You may also want to map standard HTML elements like headings and paragraphs to components. For this, you can configure a custom [Markdoc node][markdoc-nodes]. This example overrides Markdoc's `heading` node to render a `Heading` component, passing the built-in `level` attribute as a prop:
 
 ```js
-// astro.config.mjs
-import { defineConfig } from 'astro/config';
-import markdoc from '@astrojs/markdoc';
-
-// https://astro.build/config
-export default defineConfig({
-  integrations: [
-    markdoc({
-      nodes: {
-        heading: {
-          render: 'Heading',
-          // Markdoc requires type defs for each attribute.
-          // These should mirror the `Props` type of the component
-          // you are rendering. 
-          // See Markdoc's documentation on defining attributes
-          // https://markdoc.dev/docs/attributes#defining-attributes
-          attributes: {
-            level: { type: String },
-          }
-        },
-      },
-    }),
-  ],
-});
-```
-
-Now, you can map the string passed to render (`'Heading'` in this example) to a component import. This is configured from the `<Content />` component used to render your Markdoc using the `components` prop:
-
-```astro
----
-import { getEntryBySlug } from 'astro:content';
-import Heading from '../components/Heading.astro';
-
-const entry = await getEntryBySlug('docs', 'why-markdoc');
-const { Content } = await entry.render();
----
-
-<Content
-  components={{ Heading }}
-/>
+// markdoc.config.mjs
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import Heading from './src/components/Heading.astro';
+
+export default defineMarkdocConfig({
+  nodes: {
+    heading: {
+      render: Heading,
+      attributes: {
+        // Pass the attributes from Markdoc's default heading node
+        // as component props.
+        level: { type: String },
+      }
+    },
+  },
+})
 ```
 
 Now, all Markdown headings will render with the `Heading.astro` component. This example uses a level 3 heading, automatically passing `level: 3` as the component prop:
@@ -215,26 +184,26 @@ This example wraps a `Aside.tsx` component with a `ClientAside.astro` wrapper:
 import Aside from './Aside';
 ---
 
-<Aside client:load />
+<Aside {...Astro.props} client:load />
 ```
 
-This component [can be applied via the `components` prop](#render-markdoc-nodes--html-elements-as-astro-components):
-
-```astro
----
-// src/pages/why-markdoc.astro
-import { getEntryBySlug } from 'astro:content';
-import ClientAside from '../components/ClientAside.astro';
-
-const entry = await getEntryBySlug('docs', 'why-markdoc');
-const { Content } = await entry.render();
----
+This component can be passed to the `render` prop for any [tag][markdoc-tags] or [node][markdoc-nodes] in your config:
 
-<Content
-  components={{
-    Aside: ClientAside,
-  }}
-/>
+```js
+// markdoc.config.mjs
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import Aside from './src/components/Aside.astro';
+
+export default defineMarkdocConfig({
+  tags: {
+    aside: {
+      render: Aside,
+      attributes: {
+        type: { type: String },
+      }
+    },
+  },
+})
 ```
 
 ### Access frontmatter and content collection information from your templates
@@ -253,35 +222,29 @@ The `$entry` object matches [the `CollectionEntry` type](https://docs.astro.buil
 
 ### 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).
+The `markdoc.config.mjs|ts` file accepts [all Markdoc configuration options](https://markdoc.dev/docs/config), including [tags](https://markdoc.dev/docs/tags) and [functions](https://markdoc.dev/docs/functions).
 
-You can pass these options from the `markdoc()` integration in your `astro.config`. This example adds a global `getCountryEmoji` function:
+You can pass these options from the default export in your `markdoc.config.mjs|ts` file:
 
 ```js
-// astro.config.mjs
-import { defineConfig } from 'astro/config';
-import markdoc from '@astrojs/markdoc';
-
-// https://astro.build/config
-export default defineConfig({
-  integrations: [
-    markdoc({
-      functions: {
-        getCountryEmoji: {
-          transform(parameters) {
-            const [country] = Object.values(parameters);
-            const countryToEmojiMap = {
-              japan: '🇯🇵',
-              spain: '🇪🇸',
-              france: '🇫🇷',
-            }
-            return countryToEmojiMap[country] ?? '🏳'
-          },
-        },
+// markdoc.config.mjs
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+
+export default defineMarkdocConfig({
+  functions: {
+    getCountryEmoji: {
+      transform(parameters) {
+        const [country] = Object.values(parameters);
+        const countryToEmojiMap = {
+          japan: '🇯🇵',
+          spain: '🇪🇸',
+          france: '🇫🇷',
+        }
+        return countryToEmojiMap[country] ?? '🏳'
       },
-    }),
-  ],
-});
+    },
+  },
+})
 ```
 
 Now, you can call this function from any Markdoc content entry:
@@ -290,47 +253,46 @@ Now, you can call this function from any Markdoc content entry:
 ¡Hola {% getCountryEmoji("spain") %}!
 ```
 
-:::note
-These options will be applied during [the Markdoc "transform" phase](https://markdoc.dev/docs/render#transform). This is run **at build time** (rather than server request time) both for static and SSR Astro projects. If you need to define configuration at runtime (ex. SSR variables), [see the next section](#define-markdoc-configuration-at-runtime).
-:::
-
 📚 [See the Markdoc documentation](https://markdoc.dev/docs/functions#creating-a-custom-function) for more on using variables or functions in your content.
 
-### Define Markdoc configuration at runtime
+### Pass Markdoc variables
 
-You may need to define Markdoc configuration at the component level, rather than the `astro.config.mjs` level. This is useful when mapping props and SSR parameters to [Markdoc variables](https://markdoc.dev/docs/variables).
+You may need to pass [variables][markdoc-variables] to your content. This is useful when passing SSR parameters like A/B tests.
 
-Astro recommends running the Markdoc transform step manually. This allows you to define your configuration and call Markdoc's rendering functions in a `.astro` file directly, ignoring any Markdoc config in your `astro.config.mjs`.
+Variables can be passed as props via the `Content` component:
 
-You will need to install the `@markdoc/markdoc` package into your project first:
+```astro
+---
+import { getEntryBySlug } from 'astro:content';
 
-```sh
-# Using NPM
-npm install @markdoc/markdoc
-# Using Yarn
-yarn add @markdoc/markdoc
-# Using PNPM
-pnpm add @markdoc/markdoc
+const entry = await getEntryBySlug('docs', 'why-markdoc');
+const { Content } = await entry.render();
+---
+
+<!--Pass the `abTest` param as a variable-->
+<Content abTestGroup={Astro.params.abTestGroup} />
 ```
 
-Now, you can define Markdoc configuration options using `Markdock.transform()`.
+Now, `abTestGroup` is available as a variable in `docs/why-markdoc.mdoc`:
 
-This example defines an `abTestGroup` Markdoc variable based on an SSR param, transforming the raw entry `body`. The result is rendered using the `Renderer` component provided by `@astrojs/markdoc`:
+```md
+{% if $abTestGroup === 'image-optimization-lover' %}
 
-```astro
----
-import Markdoc from '@markdoc/markdoc';
-import { Renderer } from '@astrojs/markdoc/components';
-import { getEntryBySlug } from 'astro:content';
+Let me tell you about image optimization...
 
-const { body } = await getEntryBySlug('docs', 'with-ab-test');
-const ast = Markdoc.parse(body);
-const content = Markdoc.transform({
-  variables: { abTestGroup: Astro.params.abTestGroup },
-}, ast);
----
+{% /if %}
+```
 
-<Renderer {content} components={{ /* same `components` prop used by the `Content` component */ }} />
+To make a variable global to all Markdoc files, you can use the `variables` attribute from your `markdoc.config.mjs|ts`:
+
+```js
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+
+export default defineMarkdocConfig({
+  variables: {
+    environment: process.env.IS_PROD ? 'prod' : 'dev',
+  }
+})
 ```
 
 ## Examples
@@ -360,3 +322,5 @@ See [CHANGELOG.md](https://github.com/withastro/astro/tree/main/packages/integra
 [markdoc-tags]: https://markdoc.dev/docs/tags
 
 [markdoc-nodes]: https://markdoc.dev/docs/nodes
+
+[markdoc-variables]: https://markdoc.dev/docs/variables

package/components/Renderer.astro

@@ -1,20 +1,17 @@
 ---
-import type { RenderableTreeNode } from '@markdoc/markdoc';
-import type { AstroInstance } from 'astro';
-import { validateComponentsProp } from '../dist/utils.js';
+import type { Config } from '@markdoc/markdoc';
+import Markdoc from '@markdoc/markdoc';
 import { ComponentNode, createTreeNode } from './TreeNode.js';
 
 type Props = {
-	content: RenderableTreeNode;
-	components?: Record<string, AstroInstance['default']>;
+	config: Config;
+	stringifiedAst: string;
 };
 
-const { content, components } = Astro.props as Props;
+const { stringifiedAst, config } = Astro.props as Props;
 
-// Will throw if components is invalid
-if (components) {
-	validateComponentsProp(components);
-}
+const ast = Markdoc.Ast.fromJSON(stringifiedAst);
+const content = Markdoc.transform(ast, config);
 ---
 
-<ComponentNode treeNode={createTreeNode(content, components)} />
+<ComponentNode treeNode={createTreeNode(content)} />

package/components/TreeNode.ts

@@ -1,8 +1,7 @@
 import type { AstroInstance } from 'astro';
 import type { RenderableTreeNode } from '@markdoc/markdoc';
-import { createComponent, renderComponent, render } from 'astro/runtime/server/index.js';
 import Markdoc from '@markdoc/markdoc';
-import { MarkdocError, isCapitalized } from '../dist/utils.js';
+import { createComponent, renderComponent, render } from 'astro/runtime/server/index.js';
 
 export type TreeNode =
 	| {
@@ -45,20 +44,17 @@ export const ComponentNode = createComponent({
 	propagation: 'none',
 });
 
-export function createTreeNode(
-	node: RenderableTreeNode,
-	components: Record<string, AstroInstance['default']> = {}
-): TreeNode {
+export function createTreeNode(node: RenderableTreeNode): TreeNode {
 	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];
+	if (typeof node.name === 'function') {
+		const component = node.name;
 		const props = node.attributes;
-		const children = node.children.map((child) => createTreeNode(child, components));
+		const children = node.children.map((child) => createTreeNode(child));
 
 		return {
 			type: 'component',
@@ -66,17 +62,12 @@ export function createTreeNode(
 			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)),
+			children: node.children.map((child) => createTreeNode(child)),
 		};
 	}
 }

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+import type { ConfigType as MarkdocConfig } from '@markdoc/markdoc';
+export declare function defineMarkdocConfig(config: MarkdocConfig): MarkdocConfig;

package/dist/config.js

@@ -0,0 +1,6 @@
+function defineMarkdocConfig(config) {
+  return config;
+}
+export {
+  defineMarkdocConfig
+};

package/dist/default-config.d.ts

@@ -0,0 +1,5 @@
+import type { ConfigType as MarkdocConfig } from '@markdoc/markdoc';
+import type { ContentEntryModule } from 'astro';
+export declare function applyDefaultConfig(config: MarkdocConfig, ctx: {
+    entry: ContentEntryModule;
+}): MarkdocConfig;

package/dist/default-config.js

@@ -0,0 +1,13 @@
+function applyDefaultConfig(config, ctx) {
+  return {
+    ...config,
+    variables: {
+      entry: ctx.entry,
+      ...config.variables
+    }
+    // TODO: heading ID calculation, Shiki syntax highlighting
+  };
+}
+export {
+  applyDefaultConfig
+};

package/dist/experimental-assets-config.d.ts

@@ -0,0 +1,2 @@
+import type { Config as MarkdocConfig } from '@markdoc/markdoc';
+export declare const experimentalAssetsConfig: MarkdocConfig;

package/dist/experimental-assets-config.js

@@ -0,0 +1,25 @@
+import Markdoc from "@markdoc/markdoc";
+import { Image } from "astro:assets";
+const experimentalAssetsConfig = {
+  nodes: {
+    image: {
+      attributes: {
+        ...Markdoc.nodes.image.attributes,
+        __optimizedSrc: { type: "Object" }
+      },
+      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);
+        }
+      }
+    }
+  }
+};
+export {
+  experimentalAssetsConfig
+};

package/dist/index.d.ts

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