@astrojs/markdoc 0.1.2 → 0.1.3

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @astrojs/markdoc@0.1.2 build /home/runner/work/astro/astro/packages/integrations/markdoc
+> @astrojs/markdoc@0.1.3 build /home/runner/work/astro/astro/packages/integrations/markdoc
 > astro-scripts build "src/**/*.ts" && tsc
 

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @astrojs/markdoc
 
+## 0.1.3
+
+### Patch Changes
+
+- [#7045](https://github.com/withastro/astro/pull/7045) [`3a9f72c7f`](https://github.com/withastro/astro/commit/3a9f72c7f30ed173438fd0a222a094e5997b917d) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Improve Markdoc validation errors with full message and file preview.
+
+- Updated dependencies [[`48395c815`](https://github.com/withastro/astro/commit/48395c81522f7527126699c4f185f7b4488a4b9a), [`630f8c8ef`](https://github.com/withastro/astro/commit/630f8c8ef68fedfa393899c13a072e50145895e8)]:
+  - astro@2.4.4
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -143,28 +143,26 @@ Use tags like this fancy "aside" to add some *flair* to your docs.
 
 #### Render Markdoc nodes / HTML elements as Astro components
 
-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:
+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, and passes through [Markdoc's default attributes for headings](https://markdoc.dev/docs/nodes#built-in-nodes).
 
 ```js
 // markdoc.config.mjs
-import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import { defineMarkdocConfig, Markdoc } 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 },
-      }
+      attributes: Markdoc.nodes.heading.attributes,
     },
   },
 })
 ```
 
-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:
+Now, all Markdown headings will render with the `Heading.astro` component, and pass these `attributes` as component props. For headings, Markdoc provides a `level` attribute containing the numeric heading level.
+
+This example uses a level 3 heading, automatically passing `level: 3` as the component prop:
 
 ```md
 ### I'm a level 3 heading!

package/dist/config.d.ts

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

package/dist/config.js

@@ -1,6 +1,8 @@
+import { default as default2 } from "@markdoc/markdoc";
 function defineMarkdocConfig(config) {
   return config;
 }
 export {
+  default2 as Markdoc,
   defineMarkdocConfig
 };

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,9 +1,9 @@
 import Markdoc from "@markdoc/markdoc";
 import fs from "node:fs";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { isValidUrl, MarkdocError, parseFrontmatter, prependForwardSlash } from "./utils.js";
 import { emitESMImage } from "astro/assets";
-import { bold, red } from "kleur/colors";
+import { bold, red, yellow } from "kleur/colors";
 import { applyDefaultConfig } from "./default-config.js";
 import { loadMarkdocConfig } from "./load-config.js";
 function markdocIntegration(legacyConfig) {
@@ -15,13 +15,14 @@ function markdocIntegration(legacyConfig) {
     );
     process.exit(0);
   }
+  let markdocConfigResult;
   return {
     name: "@astrojs/markdoc",
     hooks: {
       "astro:config:setup": async (params) => {
         const { config: astroConfig, addContentEntryType } = params;
-        const configLoadResult = await loadMarkdocConfig(astroConfig);
-        const userMarkdocConfig = (configLoadResult == null ? void 0 : configLoadResult.config) ?? {};
+        markdocConfigResult = await loadMarkdocConfig(astroConfig);
+        const userMarkdocConfig = (markdocConfigResult == null ? void 0 : markdocConfigResult.config) ?? {};
         function getEntryInfo({ fileUrl, contents }) {
           const parsed = parseFrontmatter(contents, fileURLToPath(fileUrl));
           return {
@@ -39,14 +40,26 @@ function markdocIntegration(legacyConfig) {
             const pluginContext = this;
             const markdocConfig = applyDefaultConfig(userMarkdocConfig, { entry });
             const validationErrors = Markdoc.validate(ast, markdocConfig).filter((e) => {
-              return e.error.id !== "variable-undefined";
+              return (
+                // Ignore `variable-undefined` errors.
+                // Variables can be configured at runtime,
+                // so we cannot validate them at build time.
+                e.error.id !== "variable-undefined" && (e.error.level === "error" || e.error.level === "critical")
+              );
             });
             if (validationErrors.length) {
+              const frontmatterBlockOffset = entry._internal.rawData.split("\n").length + 2;
               throw new MarkdocError({
                 message: [
-                  `**${String(entry.collection)} \u2192 ${String(entry.id)}** failed to validate:`,
-                  ...validationErrors.map((e) => e.error.id)
-                ].join("\n")
+                  `**${String(entry.collection)} \u2192 ${String(entry.id)}** contains invalid content:`,
+                  ...validationErrors.map((e) => `- ${e.error.message}`)
+                ].join("\n"),
+                location: {
+                  // Error overlay does not support multi-line or ranges.
+                  // Just point to the first line.
+                  line: frontmatterBlockOffset + validationErrors[0].lines[0],
+                  file: viteId
+                }
               });
             }
             if (astroConfig.experimental.assets) {
@@ -56,29 +69,41 @@ function markdocIntegration(legacyConfig) {
                 filePath: entry._internal.filePath
               });
             }
-            const code = {
+            return {
               code: `import { jsx as h } from 'astro/jsx-runtime';
 import { applyDefaultConfig } from '@astrojs/markdoc/default-config';
 import { Renderer } from '@astrojs/markdoc/components';
-import * as entry from ${JSON.stringify(viteId + "?astroContent")};${configLoadResult ? `
-import userConfig from ${JSON.stringify(configLoadResult.fileUrl.pathname)};` : ""}${astroConfig.experimental.assets ? `
+import * as entry from ${JSON.stringify(viteId + "?astroContent")};${markdocConfigResult ? `
+import userConfig from ${JSON.stringify(
+                markdocConfigResult.fileUrl.pathname
+              )};` : ""}${astroConfig.experimental.assets ? `
 import { experimentalAssetsConfig } from '@astrojs/markdoc/experimental-assets-config';` : ""}
 const stringifiedAst = ${JSON.stringify(
                 /* Double stringify to encode *as* stringified JSON */
                 JSON.stringify(ast)
               )};
 export async function Content (props) {
-	const config = applyDefaultConfig(${configLoadResult ? "{ ...userConfig, variables: { ...userConfig.variables, ...props } }" : "{ variables: props }"}, { entry });${astroConfig.experimental.assets ? `
+	const config = applyDefaultConfig(${markdocConfigResult ? "{ ...userConfig, variables: { ...userConfig.variables, ...props } }" : "{ variables: props }"}, { entry });${astroConfig.experimental.assets ? `
 config.nodes = { ...experimentalAssetsConfig.nodes, ...config.nodes };` : ""}
 	return h(Renderer, { stringifiedAst, config }); };`
             };
-            return code;
           },
           contentModuleTypes: await fs.promises.readFile(
             new URL("../template/content-module-types.d.ts", import.meta.url),
             "utf-8"
           )
         });
+      },
+      "astro:server:setup": async ({ server }) => {
+        server.watcher.on("all", (event, entry) => {
+          if (pathToFileURL(entry).pathname === (markdocConfigResult == null ? void 0 : markdocConfigResult.fileUrl.pathname)) {
+            console.log(
+              yellow(
+                `${bold("[Markdoc]")} Restart the dev server for config changes to take effect.`
+              )
+            );
+          }
+        });
       }
     }
   };

package/dist/load-config.d.ts

@@ -1,14 +1,7 @@
+import type { Config as MarkdocConfig } from '@markdoc/markdoc';
 import type { AstroConfig } from 'astro';
-export declare function loadMarkdocConfig(astroConfig: Pick<AstroConfig, 'root'>): Promise<{
-    config: Readonly<Partial<{
-        nodes: Partial<Record<import("@markdoc/markdoc").NodeType, import("@markdoc/markdoc").Schema<Readonly<Partial<any>>, string>>>;
-        tags: Record<string, import("@markdoc/markdoc").Schema<Readonly<Partial<any>>, string>>;
-        variables: Record<string, any>;
-        functions: Record<string, import("@markdoc/markdoc").ConfigFunction>;
-        partials: Record<string, any>;
-        validation?: {
-            validateFunctions?: boolean | undefined;
-        } | undefined;
-    }>>;
+export type MarkdocConfigResult = {
+    config: MarkdocConfig;
     fileUrl: URL;
-} | undefined>;
+};
+export declare function loadMarkdocConfig(astroConfig: Pick<AstroConfig, 'root'>): Promise<MarkdocConfigResult | undefined>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrojs/markdoc",
   "description": "Add support for Markdoc pages in your Astro site",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "types": "./dist/index.d.ts",
   "author": "withastro",
@@ -34,7 +34,7 @@
     "zod": "^3.17.3"
   },
   "peerDependencies": {
-    "astro": "^2.4.0"
+    "astro": "^2.4.4"
   },
   "devDependencies": {
     "@types/chai": "^4.3.1",
@@ -46,7 +46,7 @@
     "mocha": "^9.2.2",
     "rollup": "^3.20.1",
     "vite": "^4.3.1",
-    "astro": "2.4.0",
+    "astro": "2.4.4",
     "astro-scripts": "0.0.14"
   },
   "engines": {

package/src/config.ts

@@ -1,4 +1,5 @@
 import type { ConfigType as MarkdocConfig } from '@markdoc/markdoc';
+export { default as Markdoc } from '@markdoc/markdoc';
 
 export function defineMarkdocConfig(config: MarkdocConfig): MarkdocConfig {
 	return config;

package/src/index.ts

@@ -1,15 +1,16 @@
+/* eslint-disable no-console */
 import type { 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 { fileURLToPath, pathToFileURL } from 'node:url';
 import { 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 { bold, red } from 'kleur/colors';
+import { bold, red, yellow } from 'kleur/colors';
 import type * as rollup from 'rollup';
 import { applyDefaultConfig } from './default-config.js';
-import { loadMarkdocConfig } from './load-config.js';
+import { loadMarkdocConfig, type MarkdocConfigResult } from './load-config.js';
 
 type SetupHookParams = HookParameters<'astro:config:setup'> & {
 	// `contentEntryType` is not a public API
@@ -17,9 +18,8 @@ type SetupHookParams = HookParameters<'astro:config:setup'> & {
 	addContentEntryType: (contentEntryType: ContentEntryType) => void;
 };
 
-export default function markdocIntegration(legacyConfig: any): AstroIntegration {
+export default function markdocIntegration(legacyConfig?: any): AstroIntegration {
 	if (legacyConfig) {
-		// eslint-disable-next-line no-console
 		console.log(
 			`${red(
 				bold('[Markdoc]')
@@ -27,14 +27,15 @@ export default function markdocIntegration(legacyConfig: any): AstroIntegration
 		);
 		process.exit(0);
 	}
+	let markdocConfigResult: MarkdocConfigResult | undefined;
 	return {
 		name: '@astrojs/markdoc',
 		hooks: {
 			'astro:config:setup': async (params) => {
 				const { config: astroConfig, addContentEntryType } = params as SetupHookParams;
 
-				const configLoadResult = await loadMarkdocConfig(astroConfig);
-				const userMarkdocConfig = configLoadResult?.config ?? {};
+				markdocConfigResult = await loadMarkdocConfig(astroConfig);
+				const userMarkdocConfig = markdocConfigResult?.config ?? {};
 
 				function getEntryInfo({ fileUrl, contents }: { fileUrl: URL; contents: string }) {
 					const parsed = parseFrontmatter(contents, fileURLToPath(fileUrl));
@@ -54,17 +55,28 @@ export default function markdocIntegration(legacyConfig: any): AstroIntegration
 						const markdocConfig = applyDefaultConfig(userMarkdocConfig, { entry });
 
 						const validationErrors = Markdoc.validate(ast, markdocConfig).filter((e) => {
-							// Ignore `variable-undefined` errors.
-							// Variables can be configured at runtime,
-							// so we cannot validate them at build time.
-							return e.error.id !== 'variable-undefined';
+							return (
+								// Ignore `variable-undefined` errors.
+								// Variables can be configured at runtime,
+								// so we cannot validate them at build time.
+								e.error.id !== 'variable-undefined' &&
+								(e.error.level === 'error' || e.error.level === 'critical')
+							);
 						});
 						if (validationErrors.length) {
+							// Heuristic: take number of newlines for `rawData` and add 2 for the `---` fences
+							const frontmatterBlockOffset = entry._internal.rawData.split('\n').length + 2;
 							throw new MarkdocError({
 								message: [
-									`**${String(entry.collection)} → ${String(entry.id)}** failed to validate:`,
-									...validationErrors.map((e) => e.error.id),
+									`**${String(entry.collection)} → ${String(entry.id)}** contains invalid content:`,
+									...validationErrors.map((e) => `- ${e.error.message}`),
 								].join('\n'),
+								location: {
+									// Error overlay does not support multi-line or ranges.
+									// Just point to the first line.
+									line: frontmatterBlockOffset + validationErrors[0].lines[0],
+									file: viteId,
+								},
 							});
 						}
 
@@ -76,13 +88,15 @@ export default function markdocIntegration(legacyConfig: any): AstroIntegration
 							});
 						}
 
-						const code = {
+						return {
 							code: `import { jsx as h } from 'astro/jsx-runtime';
 import { applyDefaultConfig } from '@astrojs/markdoc/default-config';
 import { Renderer } from '@astrojs/markdoc/components';
 import * as entry from ${JSON.stringify(viteId + '?astroContent')};${
-								configLoadResult
-									? `\nimport userConfig from ${JSON.stringify(configLoadResult.fileUrl.pathname)};`
+								markdocConfigResult
+									? `\nimport userConfig from ${JSON.stringify(
+											markdocConfigResult.fileUrl.pathname
+									  )};`
 									: ''
 							}${
 								astroConfig.experimental.assets
@@ -94,7 +108,7 @@ const stringifiedAst = ${JSON.stringify(
 							)};
 export async function Content (props) {
 	const config = applyDefaultConfig(${
-		configLoadResult
+		markdocConfigResult
 			? '{ ...userConfig, variables: { ...userConfig.variables, ...props } }'
 			: '{ variables: props }'
 	}, { entry });${
@@ -104,7 +118,6 @@ export async function Content (props) {
 							}
 	return h(Renderer, { stringifiedAst, config }); };`,
 						};
-						return code;
 					},
 					contentModuleTypes: await fs.promises.readFile(
 						new URL('../template/content-module-types.d.ts', import.meta.url),
@@ -112,6 +125,17 @@ export async function Content (props) {
 					),
 				});
 			},
+			'astro:server:setup': async ({ server }) => {
+				server.watcher.on('all', (event, entry) => {
+					if (pathToFileURL(entry).pathname === markdocConfigResult?.fileUrl.pathname) {
+						console.log(
+							yellow(
+								`${bold('[Markdoc]')} Restart the dev server for config changes to take effect.`
+							)
+						);
+					}
+				});
+			},
 		},
 	};
 }

package/src/load-config.ts

@@ -11,7 +11,14 @@ const SUPPORTED_MARKDOC_CONFIG_FILES = [
 	'markdoc.config.ts',
 ];
 
-export async function loadMarkdocConfig(astroConfig: Pick<AstroConfig, 'root'>) {
+export type MarkdocConfigResult = {
+	config: MarkdocConfig;
+	fileUrl: URL;
+};
+
+export async function loadMarkdocConfig(
+	astroConfig: Pick<AstroConfig, 'root'>
+): Promise<MarkdocConfigResult | undefined> {
 	let markdocConfigUrl: URL | undefined;
 	for (const filename of SUPPORTED_MARKDOC_CONFIG_FILES) {
 		const filePath = new URL(filename, astroConfig.root);