feat: markdown config typechecking

.changeset/forty-plants-hope.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/markdown-remark': patch
+---
+
+Improved type checking

.changeset/small-months-speak.md

@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Improved markdown config type checking

packages/astro/package.json

@@ -154,6 +154,7 @@
     "@types/resolve": "^1.20.1",
     "@types/rimraf": "^3.0.2",
     "@types/send": "^0.17.1",
+    "@types/unist": "^2.0.6",
     "@types/yargs-parser": "^21.0.0",
     "astro-scripts": "workspace:*",
     "chai": "^4.3.6",

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

@@ -349,14 +349,24 @@ export interface AstroUserConfig {
 		 */
 		drafts?: boolean;
 
+		/**
+		 * @docs
+		 * @name markdown.mode
+		 * @type {'md' | 'mdx'}
+		 * @default `mdx`
+		 * @description
+		 * Control wheater to allow components inside markdown files ('mdx') or not ('md').
+		 */
+		mode?: 'md' | 'mdx';
+
 		/**
 		 * @docs
 		 * @name markdown.shikiConfig
-		 * @type {ShikiConfig}
+		 * @typeraw {Partial<ShikiConfig>}
 		 * @description
 		 * Shiki configuration options. See [the markdown configuration docs](https://docs.astro.build/en/guides/markdown-content/#shiki-configuration) for usage.
 		 */
-		shikiConfig?: ShikiConfig;
+		shikiConfig?: Partial<ShikiConfig>;
 
 		/**
 		 * @docs

packages/astro/src/core/config.ts

@@ -2,6 +2,7 @@ import type { AstroConfig, AstroUserConfig, CLIFlags } from '../@types/astro';
 import type { Arguments as Flags } from 'yargs-parser';
 import type * as Postcss from 'postcss';
 
+import { astroMarkdownOptions } from '@astrojs/markdown-remark';
 import * as colors from 'kleur/colors';
 import path from 'path';
 import { pathToFileURL, fileURLToPath } from 'url';
@@ -13,6 +14,12 @@ import postcssrc from 'postcss-load-config';
 import { arraify, isObject } from './util.js';
 import { appendForwardSlash, trimSlashes } from './path.js';
 
+// These two imports make astroMarkdownOptions work
+// If you remove them, TypeScript throws an error similar to this:
+// `The inferred type of 'AstroConfigSchema' cannot be named without a reference to '../../../markdown/remark/node_modules/@types/unist'. This is likely not portable. A type annotation is necessary`
+import type {} from 'shiki';
+import type {} from 'unist';
+
 load.use([loadTypeScript]);
 
 interface PostCSSConfigResult {
@@ -140,25 +147,7 @@ export const AstroConfigSchema = z.object({
 		})
 		.optional()
 		.default({}),
-	markdown: z
-		.object({
-			drafts: z.boolean().optional().default(false),
-			mode: z
-				.union([z.literal('md'), z.literal('mdx')])
-				.optional()
-				.default('md'),
-			syntaxHighlight: z
-				.union([z.literal('shiki'), z.literal('prism'), z.literal(false)])
-				.optional()
-				.default('shiki'),
-			// TODO: add better type checking
-			shikiConfig: z.any().optional().default({}),
-			remarkPlugins: z.array(z.any()).optional().default([]),
-			rehypePlugins: z.array(z.any()).optional().default([]),
-		})
-		.passthrough()
-		.optional()
-		.default({}),
+	markdown: astroMarkdownOptions.default({}),
 	vite: z.any().optional().default({}),
 	experimental: z
 		.object({

packages/markdown/remark/package.json

@@ -43,11 +43,13 @@
     "shiki": "^0.10.1",
     "unified": "^10.1.2",
     "unist-util-map": "^3.0.1",
-    "unist-util-visit": "^4.1.0"
+    "unist-util-visit": "^4.1.0",
+    "zod": "^3.14.3"
   },
   "devDependencies": {
     "@types/github-slugger": "^1.3.0",
     "@types/prismjs": "^1.26.0",
+    "@types/unist": "^2.0.6",
     "astro-scripts": "workspace:*"
   }
 }

packages/markdown/remark/src/index.ts

@@ -1,4 +1,4 @@
-import type { AstroMarkdownOptions, MarkdownRenderingOptions, ShikiConfig, Plugin } from './types';
+import { MarkdownRenderingOptions, astroMarkdownOptions } from './types.js';
 
 import createCollectHeaders from './rehype-collect-headers.js';
 import scopedStyles from './remark-scoped-styles.js';
@@ -20,7 +20,7 @@ import rehypeStringify from 'rehype-stringify';
 import rehypeRaw from 'rehype-raw';
 import matter from 'gray-matter';
 
-export { AstroMarkdownOptions, MarkdownRenderingOptions, ShikiConfig, Plugin };
+export * from './types.js';
 
 /** Internal utility for rendering a full markdown file and extracting Frontmatter data */
 export async function renderMarkdownWithFrontmatter(
@@ -38,11 +38,8 @@ export const DEFAULT_REHYPE_PLUGINS = ['rehype-slug'];
 
 /** Shared utility for rendering markdown */
 export async function renderMarkdown(content: string, opts?: MarkdownRenderingOptions | null) {
-	let { remarkPlugins = [], rehypePlugins = [] } = opts ?? {};
+	let { mode, syntaxHighlight, shikiConfig, remarkPlugins, rehypePlugins } = astroMarkdownOptions.parse(opts ?? {});
 	const scopedClassName = opts?.$?.scopedClassName;
-	const mode = opts?.mode ?? 'mdx';
-	const syntaxHighlight = opts?.syntaxHighlight ?? 'shiki';
-	const shikiConfig = opts?.shikiConfig ?? {};
 	const isMDX = mode === 'mdx';
 	const { headers, rehypeCollectHeaders } = createCollectHeaders();
 

packages/markdown/remark/src/remark-shiki.ts

@@ -1,34 +1,7 @@
 import type * as shiki from 'shiki';
 import { getHighlighter } from 'shiki';
 import { visit } from 'unist-util-visit';
-
-export interface ShikiConfig {
-	/**
-	 * The languages loaded to Shiki.
-	 * Supports all languages listed here: https://github.com/shikijs/shiki/blob/main/docs/languages.md#all-languages
-	 * Instructions for loading a custom language: https://github.com/shikijs/shiki/blob/main/docs/languages.md#supporting-your-own-languages-with-shiki
-	 *
-	 * @default []
-	 */
-	langs?: shiki.ILanguageRegistration[];
-	/**
-	 * The styling theme.
-	 * Supports all themes listed here: https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes
-	 * Instructions for loading a custom theme: https://github.com/shikijs/shiki/blob/main/docs/themes.md#loading-theme
-	 *
-	 * @default "github-dark"
-	 */
-	theme?: shiki.IThemeRegistration;
-	/**
-	 * Enable word wrapping.
-	 *  - true: enabled.
-	 *  - false: enabled.
-	 *  - null: All overflow styling removed. Code will overflow the element by default.
-	 *
-	 * @default false
-	 */
-	wrap?: boolean | null;
-}
+import type { ShikiConfig } from './types.js';
 
 /**
  * getHighlighter() is the most expensive step of Shiki. Instead of calling it on every page,
@@ -38,7 +11,7 @@ export interface ShikiConfig {
 const highlighterCacheAsync = new Map<string, Promise<shiki.Highlighter>>();
 
 const remarkShiki = async (
-	{ langs = [], theme = 'github-dark', wrap = false }: ShikiConfig,
+	{ langs, theme, wrap }: ShikiConfig,
 	scopedClassName?: string | null
 ) => {
 	const cacheID: string = typeof theme === 'string' ? theme : theme.name;

packages/markdown/remark/src/types.ts

@@ -1,16 +1,42 @@
 import type * as unified from 'unified';
-import type { ShikiConfig } from './remark-shiki';
-export { ShikiConfig };
+import type { Node } from 'unist';
+import type { ILanguageRegistration, IThemeRegistration, Theme } from 'shiki';
+import { BUNDLED_THEMES } from 'shiki';
+import { z } from 'zod';
 
-export type Plugin = string | [string, any] | unified.Plugin | [unified.Plugin, any];
+export { Node };
+export type PluginFunction<PluginParameters extends any[] = any[], Input = Node, Output = Input> = unified.Plugin<PluginParameters, Input, Output>;
 
-export interface AstroMarkdownOptions {
-	mode?: 'md' | 'mdx';
-	syntaxHighlight?: 'shiki' | 'prism' | false;
-	shikiConfig?: ShikiConfig;
-	remarkPlugins?: Plugin[];
-	rehypePlugins?: Plugin[];
-}
+const plugin = z.union([
+	z.string(),
+	z.tuple([z.string(), z.any()]),
+	z.custom<PluginFunction>((data) => typeof data === 'function'),
+	z.tuple([z.custom<PluginFunction>((data) => typeof data === 'function'), z.any()]),
+]);
+
+export type Plugin = z.infer<typeof plugin>;
+
+const shikiConfig = z.object({
+	langs: z.custom<ILanguageRegistration>().array().default([]),
+	theme: z
+		.enum(BUNDLED_THEMES as [Theme, ...Theme[]])
+		.or(z.custom<IThemeRegistration>())
+		.default('github-dark'),
+	wrap: z.boolean().or(z.null()).default(false),
+});
+
+export type ShikiConfig = z.infer<typeof shikiConfig>;
+
+export const astroMarkdownOptions = z.object({
+	mode: z.enum(['md', 'mdx']).default('mdx'),
+	drafts: z.boolean().default(false),
+	syntaxHighlight: z.union([z.literal('shiki'), z.literal('prism'), z.literal(false)]).default('shiki'),
+	shikiConfig: shikiConfig.default({}),
+	remarkPlugins: plugin.array().default([]),
+	rehypePlugins: plugin.array().default([]),
+});
+
+export type AstroMarkdownOptions = z.infer<typeof astroMarkdownOptions>;
 
 export interface MarkdownRenderingOptions extends Partial<AstroMarkdownOptions> {
 	/** @internal */