@astrojs/markdoc 0.0.0-head-prop-20230323183456

package/dist/utils.d.ts

@@ -0,0 +1,50 @@
+/// <reference types="node" />
+import type { AstroInstance } from 'astro';
+import matter from 'gray-matter';
+import type fsMod from 'node:fs';
+/**
+ * Match YAML exception handling from Astro core errors
+ * @see 'astro/src/core/errors.ts'
+ */
+export declare function parseFrontmatter(fileContents: string, filePath: string): matter.GrayMatterFile<string>;
+/**
+ * Matches AstroError object with types like error codes stubbed out
+ * @see 'astro/src/core/errors/errors.ts'
+ */
+export declare class MarkdocError extends Error {
+    errorCode: number;
+    loc: ErrorLocation | undefined;
+    title: string | undefined;
+    hint: string | undefined;
+    frame: string | undefined;
+    type: string;
+    constructor(props: ErrorProperties, ...params: any);
+}
+interface ErrorLocation {
+    file?: string;
+    line?: number;
+    column?: number;
+}
+interface ErrorProperties {
+    code?: number;
+    title?: string;
+    name?: string;
+    message?: string;
+    location?: ErrorLocation;
+    hint?: string;
+    stack?: string;
+    frame?: string;
+}
+/**
+ * Matches `search` function used for resolving `astro.config` files.
+ * Used by Markdoc for error handling.
+ * @see 'astro/src/core/config/config.ts'
+ */
+export declare function getAstroConfigPath(fs: typeof fsMod, root: string): string | undefined;
+/**
+ * @see 'astro/src/core/path.ts'
+ */
+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 {};

package/dist/utils.js

@@ -0,0 +1,92 @@
+import z from "astro/zod";
+import matter from "gray-matter";
+import path from "node:path";
+function parseFrontmatter(fileContents, filePath) {
+  try {
+    matter.clearCache();
+    return matter(fileContents);
+  } catch (e) {
+    if (e.name === "YAMLException") {
+      const err = e;
+      err.id = filePath;
+      err.loc = { file: e.id, line: e.mark.line + 1, column: e.mark.column };
+      err.message = e.reason;
+      throw err;
+    } else {
+      throw e;
+    }
+  }
+}
+class MarkdocError extends Error {
+  constructor(props, ...params) {
+    super(...params);
+    this.type = "MarkdocError";
+    const {
+      code = 99999,
+      name,
+      title = "MarkdocError",
+      message,
+      stack,
+      location,
+      hint,
+      frame
+    } = props;
+    this.errorCode = code;
+    this.title = title;
+    if (message)
+      this.message = message;
+    this.stack = stack ? stack : this.stack;
+    this.loc = location;
+    this.hint = hint;
+    this.frame = frame;
+  }
+}
+function getAstroConfigPath(fs, root) {
+  const paths = [
+    "astro.config.mjs",
+    "astro.config.js",
+    "astro.config.ts",
+    "astro.config.mts",
+    "astro.config.cjs",
+    "astro.config.cts"
+  ].map((p) => path.join(root, p));
+  for (const file of paths) {
+    if (fs.existsSync(file)) {
+      return file;
+    }
+  }
+}
+function prependForwardSlash(str) {
+  return str[0] === "/" ? str : "/" + str;
+}
+function validateComponentsProp(components) {
+  try {
+    componentsPropValidator.parse(components);
+  } catch (e) {
+    throw new MarkdocError({
+      message: e instanceof z.ZodError ? e.issues[0].message : "Invalid `components` prop. Ensure you are passing an object of components to <Content />"
+    });
+  }
+}
+const componentsPropValidator = z.record(
+  z.string().min(1, "Invalid `components` prop. Component names cannot be empty!").refine(
+    (value) => isCapitalized(value),
+    (value) => ({
+      message: `Invalid \`components\` prop: ${JSON.stringify(
+        value
+      )}. Component name must be capitalized. If you want to render HTML elements as components, try using a Markdoc node (https://docs.astro.build/en/guides/integrations-guide/markdoc/#render-markdoc-nodes--html-elements-as-astro-components)`
+    })
+  ),
+  z.any()
+);
+function isCapitalized(str) {
+  return str.length > 0 && str[0] === str[0].toUpperCase();
+}
+export {
+  MarkdocError,
+  getAstroConfigPath,
+  isCapitalized,
+  parseFrontmatter,
+  prependForwardSlash,
+  validateComponentsProp
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@astrojs/markdoc",
+  "description": "Add support for Markdoc pages in your Astro site",
+  "version": "0.0.0-head-prop-20230323183456",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "author": "withastro",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/withastro/astro.git",
+    "directory": "packages/integrations/markdoc"
+  },
+  "keywords": [
+    "astro-integration",
+    "astro-component",
+    "markdoc"
+  ],
+  "bugs": "https://github.com/withastro/astro/issues",
+  "homepage": "https://docs.astro.build/en/guides/integrations-guide/markdoc/",
+  "exports": {
+    ".": "./dist/index.js",
+    "./components": "./components/index.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@markdoc/markdoc": "^0.2.2",
+    "gray-matter": "^4.0.3",
+    "stringify-attributes": "^3.0.0",
+    "zod": "^3.17.3"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.3.1",
+    "@types/html-escaper": "^3.0.0",
+    "@types/mocha": "^9.1.1",
+    "astro": "0.0.0-head-prop-20230323183456",
+    "astro-scripts": "0.0.14",
+    "chai": "^4.3.6",
+    "devalue": "^4.2.0",
+    "linkedom": "^0.14.12",
+    "mocha": "^9.2.2",
+    "vite": "^4.0.3"
+  },
+  "engines": {
+    "node": ">=16.12.0"
+  },
+  "scripts": {
+    "build": "astro-scripts build \"src/**/*.ts\" && tsc",
+    "build:ci": "astro-scripts build \"src/**/*.ts\"",
+    "dev": "astro-scripts dev \"src/**/*.ts\"",
+    "test": "mocha --exit --timeout 20000",
+    "test:match": "mocha --timeout 20000 -g"
+  }
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+import type { Config } 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 {
+	getAstroConfigPath,
+	MarkdocError,
+	parseFrontmatter,
+	prependForwardSlash,
+} from './utils.js';
+
+type SetupHookParams = HookParameters<'astro:config:setup'> & {
+	// `contentEntryType` is not a public API
+	// Add type defs here
+	addContentEntryType: (contentEntryType: ContentEntryType) => void;
+};
+
+export default function markdoc(markdocConfig: Config = {}): AstroIntegration {
+	return {
+		name: '@astrojs/markdoc',
+		hooks: {
+			'astro:config:setup': async (params) => {
+				const { updateConfig, config, addContentEntryType } = params as SetupHookParams;
+
+				function getEntryInfo({ fileUrl, contents }: { fileUrl: URL; contents: string }) {
+					const parsed = parseFrontmatter(contents, fileURLToPath(fileUrl));
+					return {
+						data: parsed.data,
+						body: parsed.content,
+						slug: parsed.data.slug,
+						rawData: parsed.matter,
+					};
+				}
+				addContentEntryType({
+					extensions: ['.mdoc'],
+					getEntryInfo,
+					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) {
+	const tags = markdocConfig.tags ?? {};
+	const nodes = markdocConfig.nodes ?? {};
+
+	for (const [name, config] of Object.entries(tags)) {
+		validateRenderProperty({ type: 'tag', name, config, astroConfig });
+	}
+	for (const [name, config] of Object.entries(nodes)) {
+		validateRenderProperty({ type: 'node', name, config, astroConfig });
+	}
+}
+
+function validateRenderProperty({
+	name,
+	config,
+	type,
+	astroConfig,
+}: {
+	name: string;
+	config: { render?: string };
+	type: 'node' | 'tag';
+	astroConfig: Pick<AstroConfig, 'root'>;
+}) {
+	if (typeof config.render === 'string' && config.render.length === 0) {
+		throw new Error(
+			`Invalid ${type} configuration: ${JSON.stringify(
+				name
+			)}. The "render" property cannot be an empty string.`
+		);
+	}
+	if (typeof config.render === 'string' && !isCapitalized(config.render)) {
+		const astroConfigPath = getAstroConfigPath(fs, fileURLToPath(astroConfig.root));
+		throw new MarkdocError({
+			message: `Invalid ${type} configuration: ${JSON.stringify(
+				name
+			)}. The "render" property must reference a capitalized component name.`,
+			hint: 'If you want to render to an HTML element, see our docs on rendering Markdoc manually: https://docs.astro.build/en/guides/integrations-guide/markdoc/#render-markdoc-nodes--html-elements-as-astro-components',
+			location: astroConfigPath
+				? {
+						file: astroConfigPath,
+				  }
+				: undefined,
+		});
+	}
+}
+
+function isCapitalized(str: string) {
+	return str.length > 0 && str[0] === str[0].toUpperCase();
+}

package/src/utils.ts

@@ -0,0 +1,147 @@
+import type { AstroInstance } from 'astro';
+import z from 'astro/zod';
+import matter from 'gray-matter';
+import type fsMod from 'node:fs';
+import path from 'node:path';
+import type { ErrorPayload as ViteErrorPayload } from 'vite';
+
+/**
+ * Match YAML exception handling from Astro core errors
+ * @see 'astro/src/core/errors.ts'
+ */
+export function parseFrontmatter(fileContents: string, filePath: string) {
+	try {
+		// `matter` is empty string on cache results
+		// clear cache to prevent this
+		(matter as any).clearCache();
+		return matter(fileContents);
+	} catch (e: any) {
+		if (e.name === 'YAMLException') {
+			const err: Error & ViteErrorPayload['err'] = e;
+			err.id = filePath;
+			err.loc = { file: e.id, line: e.mark.line + 1, column: e.mark.column };
+			err.message = e.reason;
+			throw err;
+		} else {
+			throw e;
+		}
+	}
+}
+
+/**
+ * Matches AstroError object with types like error codes stubbed out
+ * @see 'astro/src/core/errors/errors.ts'
+ */
+export class MarkdocError extends Error {
+	public errorCode: number;
+	public loc: ErrorLocation | undefined;
+	public title: string | undefined;
+	public hint: string | undefined;
+	public frame: string | undefined;
+
+	type = 'MarkdocError';
+
+	constructor(props: ErrorProperties, ...params: any) {
+		super(...params);
+
+		const {
+			// Use default code for unknown errors in Astro core
+			// We don't have a best practice for integration error codes yet
+			code = 99999,
+			name,
+			title = 'MarkdocError',
+			message,
+			stack,
+			location,
+			hint,
+			frame,
+		} = props;
+
+		this.errorCode = code;
+		this.title = title;
+		if (message) this.message = message;
+		// Only set this if we actually have a stack passed, otherwise uses Error's
+		this.stack = stack ? stack : this.stack;
+		this.loc = location;
+		this.hint = hint;
+		this.frame = frame;
+	}
+}
+
+interface ErrorLocation {
+	file?: string;
+	line?: number;
+	column?: number;
+}
+
+interface ErrorProperties {
+	code?: number;
+	title?: string;
+	name?: string;
+	message?: string;
+	location?: ErrorLocation;
+	hint?: string;
+	stack?: string;
+	frame?: string;
+}
+
+/**
+ * Matches `search` function used for resolving `astro.config` files.
+ * Used by Markdoc for error handling.
+ * @see 'astro/src/core/config/config.ts'
+ */
+export function getAstroConfigPath(fs: typeof fsMod, root: string): string | undefined {
+	const paths = [
+		'astro.config.mjs',
+		'astro.config.js',
+		'astro.config.ts',
+		'astro.config.mts',
+		'astro.config.cjs',
+		'astro.config.cts',
+	].map((p) => path.join(root, p));
+
+	for (const file of paths) {
+		if (fs.existsSync(file)) {
+			return file;
+		}
+	}
+}
+
+/**
+ * @see 'astro/src/core/path.ts'
+ */
+export function prependForwardSlash(str: string) {
+	return str[0] === '/' ? str : '/' + str;
+}
+
+export function validateComponentsProp(components: Record<string, AstroInstance['default']>) {
+	try {
+		componentsPropValidator.parse(components);
+	} catch (e) {
+		throw new MarkdocError({
+			message:
+				e instanceof z.ZodError
+					? e.issues[0].message
+					: 'Invalid `components` prop. Ensure you are passing an object of components to <Content />',
+		});
+	}
+}
+
+const componentsPropValidator = z.record(
+	z
+		.string()
+		.min(1, 'Invalid `components` prop. Component names cannot be empty!')
+		.refine(
+			(value) => isCapitalized(value),
+			(value) => ({
+				message: `Invalid \`components\` prop: ${JSON.stringify(
+					value
+				)}. Component name must be capitalized. If you want to render HTML elements as components, try using a Markdoc node (https://docs.astro.build/en/guides/integrations-guide/markdoc/#render-markdoc-nodes--html-elements-as-astro-components)`,
+			})
+		),
+	z.any()
+);
+
+export function isCapitalized(str: string) {
+	return str.length > 0 && str[0] === str[0].toUpperCase();
+}

package/template/content-module-types.d.ts

@@ -0,0 +1,9 @@
+declare module 'astro:content' {
+	interface Render {
+		'.mdoc': Promise<{
+			Content(props: {
+				components?: Record<string, import('astro').AstroInstance['default']>;
+			}): import('astro').MarkdownInstance<{}>['Content'];
+		}>;
+	}
+}