MDX: Improve error handling logic on parsing meta entries

.changeset/light-cars-stay.md

@@ -0,0 +1,5 @@
+---
+'fumadocs-mdx': patch
+---
+
+Improve error handling logic on parsing meta entries

packages/mdx/package.json

@@ -57,6 +57,7 @@
     "estree-util-value-to-estree": "^3.3.3",
     "fast-glob": "^3.3.3",
     "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.0",
     "lru-cache": "^11.1.0",
     "picocolors": "^1.1.1",
     "unist-util-visit": "^5.0.0",
@@ -65,6 +66,7 @@
   "devDependencies": {
     "@fumadocs/mdx-remote": "workspace:*",
     "@types/cross-spawn": "^6.0.6",
+    "@types/js-yaml": "^4.0.9",
     "@types/mdast": "^4.0.3",
     "@types/mdx": "^2.0.13",
     "@types/react": "^19.1.2",

packages/mdx/src/config/define.ts

@@ -131,6 +131,7 @@ export function defineDocs<
     // @ts-expect-error -- internal type inferring
     meta: defineCollections({
       type: 'meta',
+      files: ['**/meta.{json,yaml}'],
       dir,
       schema: metaSchema,
       ...options?.meta,

packages/mdx/src/map/generate.ts

@@ -3,12 +3,13 @@ import * as fs from 'node:fs/promises';
 import fg from 'fast-glob';
 import { getTypeFromPath } from '@/utils/get-type-from-path';
 import type { FileInfo } from '@/config/types';
-import { type LoadedConfig } from '@/utils/config';
+import type { LoadedConfig } from '@/utils/config';
 import type { DocCollection, MetaCollection } from '@/config';
 import { validate } from '@/utils/schema';
 import { fileCache } from '@/map/file-cache';
 import matter from 'gray-matter';
 import type { AsyncRuntimeFile } from '@/runtime/types';
+import { load } from 'js-yaml';
 
 async function readFileWithCache(file: string): Promise<string> {
   const cached = fileCache.read<string>('read-file', file);
@@ -60,7 +61,8 @@ export async function generateJS(
   async function getMetaEntries(collection: MetaCollection, files: FileInfo[]) {
     const items = files.map(async (file) => {
       const source = await readFileWithCache(file.absolutePath).catch(() => '');
-      let data = source.length === 0 ? {} : JSON.parse(source);
+      let data =
+        source.length === 0 ? {} : parseMetaEntry(file.absolutePath, source);
 
       if (collection?.schema) {
         data = await validate(
@@ -237,3 +239,17 @@ export function toImportPath(file: string, dir: string): string {
 
   return importPath.replaceAll(path.sep, '/');
 }
+
+function parseMetaEntry(file: string, content: string) {
+  const extname = path.extname(file);
+  try {
+    if (extname === '.json') return JSON.parse(content);
+    if (extname === '.yaml') return load(content);
+  } catch (e) {
+    throw new Error(`Failed to parse meta file: ${file}.`, {
+      cause: e,
+    });
+  }
+
+  throw new Error(`Unknown meta file format: ${extname}, in ${file}.`);
+}

pnpm-lock.yaml

@@ -276,7 +276,7 @@ importers:
         version: 0.2.2(@content-collections/[email protected]([email protected]))([email protected])([email protected]([email protected]))([email protected])
       '@content-collections/next':
         specifier: ^0.2.6
-        version: 0.2.6(@content-collections/[email protected]([email protected]))([email protected](@babel/[email protected])(@opentelemetry/[email protected])([email protected])([email protected]([email protected]))([email protected]))
+        version: 0.2.6(@content-collections/[email protected]([email protected]))([email protected](@opentelemetry/[email protected])([email protected]([email protected]))([email protected]))
       '@types/mdx':
         specifier: ^2.0.13
         version: 2.0.13
@@ -871,7 +871,7 @@ importers:
         version: 0.2.2(@content-collections/[email protected]([email protected]))([email protected])([email protected]([email protected]))([email protected])
       '@content-collections/next':
         specifier: ^0.2.6
-        version: 0.2.6(@content-collections/[email protected]([email protected]))([email protected](@babel/[email protected])(@opentelemetry/[email protected])([email protected])([email protected]([email protected]))([email protected]))
+        version: 0.2.6(@content-collections/[email protected]([email protected]))([email protected](@opentelemetry/[email protected])([email protected]([email protected]))([email protected]))
       '@react-router/dev':
         specifier: ^7.5.3
         version: 7.5.3(@react-router/[email protected]([email protected]([email protected]([email protected]))([email protected]))([email protected]))(@types/[email protected])([email protected])([email protected])([email protected])([email protected]([email protected]([email protected]))([email protected]))([email protected])([email protected])([email protected])([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected]))([email protected])
@@ -1040,6 +1040,9 @@ importers:
       gray-matter:
         specifier: ^4.0.3
         version: 4.0.3
+      js-yaml:
+        specifier: ^4.1.0
+        version: 4.1.0
       lru-cache:
         specifier: ^11.1.0
         version: 11.1.0
@@ -1059,6 +1062,9 @@ importers:
       '@types/cross-spawn':
         specifier: ^6.0.6
         version: 6.0.6
+      '@types/js-yaml':
+        specifier: ^4.0.9
+        version: 4.0.9
       '@types/mdast':
         specifier: ^4.0.3
         version: 4.0.4
@@ -10974,7 +10980,7 @@ snapshots:
       - acorn
       - supports-color
 
-  '@content-collections/[email protected](@content-collections/[email protected]([email protected]))([email protected](@babel/[email protected])(@opentelemetry/[email protected])([email protected])([email protected]([email protected]))([email protected]))':
+  '@content-collections/[email protected](@content-collections/[email protected]([email protected]))([email protected](@opentelemetry/[email protected])([email protected]([email protected]))([email protected]))':
     dependencies:
       '@content-collections/core': 0.8.2([email protected])
       '@content-collections/integrations': 0.2.1(@content-collections/[email protected]([email protected]))