fumadocs-core 15.8.0 → 15.8.1

package/dist/source/index.d.ts

@@ -1,6 +1,46 @@
-import { ReactNode } from 'react';
-import { R as Root, I as Item, F as Folder, S as Separator } from '../definitions-Q95-psoo.js';
+import { I as Item, F as Folder, S as Separator, R as Root } from '../definitions-Q95-psoo.js';
 import { I18nConfig } from '../i18n/index.js';
+import { ReactNode } from 'react';
+
+interface FileInfo {
+    /**
+     * File path without extension
+     *
+     * @deprecated obtain it with `join(dirname, name)`
+     */
+    flattenedPath: string;
+    /**
+     * path of file (unparsed)
+     */
+    path: string;
+    /**
+     * File name without extension
+     */
+    name: string;
+    /**
+     * file extension from the last `.`, like `.md`
+     *
+     * empty string if no file extension
+     */
+    ext: string;
+    dirname: string;
+}
+interface FolderInfo {
+    /**
+     * Original path of folder
+     */
+    path: string;
+    /**
+     * folder name
+     */
+    name: string;
+    dirname: string;
+}
+declare function parseFilePath(path: string): FileInfo;
+/**
+ * @deprecated use `dirname` and `basename` directly.
+ */
+declare function parseFolderPath(path: string): FolderInfo;
 
 /**
  * In memory file system.
@@ -22,8 +62,8 @@ declare class FileSystem<File> {
 }
 
 interface LoadOptions {
-    transformers?: Transformer[];
     buildFile: (file: VirtualFile) => MetaFile | PageFile;
+    plugins?: LoaderPlugin[];
 }
 type ContentStorage<Page extends PageData = PageData, Meta extends MetaData = MetaData> = FileSystem<MetaFile<Meta> | PageFile<Page>>;
 interface MetaFile<Data extends MetaData = MetaData> {
@@ -41,7 +81,6 @@ interface PageFile<Data extends PageData = PageData> {
 }
 type Transformer = (context: {
     storage: ContentStorage;
-    options: LoadOptions;
 }) => void;
 /**
  * @returns a map of locale and its content storage.
@@ -50,45 +89,49 @@ type Transformer = (context: {
  */
 declare function loadFiles(files: VirtualFile[], options: LoadOptions, i18n: I18nConfig): Record<string, ContentStorage>;
 
-interface FileInfo {
+type LoaderPlugins<Page extends PageData, Meta extends MetaData> = LoaderPlugin<Page, Meta>[];
+interface LoaderPlugin<Page extends PageData = PageData, Meta extends MetaData = MetaData> {
     /**
-     * File path without extension
-     *
-     * @deprecated obtain it with `join(dirname, name)`
+     * transform the storage after loading
      */
-    flattenedPath: string;
+    transformStorage?: (context: {
+        storage: ContentStorage<Page, Meta>;
+    }) => void;
     /**
-     * path of file (unparsed)
+     * transform the generated page tree
      */
-    path: string;
+    transformPageTree?: PageTreeTransformer<Page, Meta>;
+}
+declare function buildPlugins<Page extends PageData, Meta extends MetaData>(plugins: LoaderPlugins<Page, Meta>): LoaderPlugin<Page, Meta>[];
+
+interface LegacyLoaderOptions {
     /**
-     * File name without extension
+     * We recommend you to use `plugins` instead
      */
-    name: string;
+    transformers?: Transformer[];
+}
+interface LegacyPageTreeOptions<Page extends PageData, Meta extends MetaData> {
     /**
-     * file extension from the last `.`, like `.md`
-     *
-     * empty string if no file extension
+     * @deprecated use `plugins` instead
      */
-    ext: string;
-    dirname: string;
-}
-interface FolderInfo {
+    attachFile?: (node: Item, file?: PageFile<Page>) => Item;
     /**
-     * Original path of folder
+     * @deprecated use `plugins` instead
      */
-    path: string;
+    attachFolder?: (node: Folder, folder: {
+        children: (PageFile<Page> | MetaFile<Meta>)[];
+    }, meta?: MetaFile<Meta>) => Folder;
     /**
-     * folder name
+     * @deprecated use `plugins` instead
      */
-    name: string;
-    dirname: string;
+    attachSeparator?: (node: Separator) => Separator;
+    /**
+     * We recommend you to use `plugins` instead
+     */
+    transformers?: PageTreeTransformer<Page, Meta>[];
 }
-declare function parseFilePath(path: string): FileInfo;
-/**
- * @deprecated use `dirname` and `basename` directly.
- */
-declare function parseFolderPath(path: string): FolderInfo;
+
+type IconResolver = (icon: string | undefined) => ReactNode;
 
 interface LoaderConfig {
     source: SourceConfig;
@@ -98,21 +141,23 @@ interface SourceConfig {
     pageData: PageData;
     metaData: MetaData;
 }
-interface LoaderOptions<T extends SourceConfig = SourceConfig, I18n extends I18nConfig | undefined = I18nConfig | undefined> {
+type LoaderOptions<Config extends SourceConfig = SourceConfig, I18n extends I18nConfig | undefined = I18nConfig | undefined> = BaseLoaderOptions<NoInfer<Config>> & {
+    source: Source<Config> | Source<Config>[];
+    /**
+     * Configure i18n
+     */
+    i18n?: I18n;
+};
+interface BaseLoaderOptions<Config extends SourceConfig> extends LegacyLoaderOptions {
     baseUrl: string;
-    icon?: NonNullable<BaseOptions['resolveIcon']>;
+    icon?: IconResolver;
     slugs?: (info: FileInfo) => string[];
     url?: UrlFn;
-    source: Source<T> | Source<T>[];
-    transformers?: Transformer[];
     /**
      * Additional options for page tree builder
      */
-    pageTree?: Partial<BaseOptions<T['pageData'], T['metaData']>>;
-    /**
-     * Configure i18n
-     */
-    i18n?: I18n;
+    pageTree?: Partial<BaseOptions> & LegacyPageTreeOptions<Config['pageData'], Config['metaData']>;
+    plugins?: LoaderPlugins<Config['pageData'], Config['metaData']>;
 }
 interface Source<Config extends SourceConfig> {
     /**
@@ -183,13 +228,19 @@ interface LoaderOutput<Config extends LoaderConfig> {
         page: Page<Config['source']['pageData']>;
         hash?: string;
     } | undefined;
+    /**
+     * @internal
+     */
     _i18n?: I18nConfig;
     /**
-     * Get list of pages from language
+     * Get a list of pages from specified language
      *
-     * @param language - If empty, the default language will be used
+     * @param language - If empty, list pages from all languages.
      */
     getPages: (language?: string) => Page<Config['source']['pageData']>[];
+    /**
+     * get each language and its pages, empty if i18n is not enabled.
+     */
     getLanguages: () => LanguageEntry<Config['source']['pageData']>[];
     /**
      * Get page with slugs
@@ -237,53 +288,36 @@ type InferMetaType<Utils extends LoaderOutput<any>> = Utils extends LoaderOutput
  */
 type UrlFn = (slugs: string[], locale?: string) => string;
 
-interface LegacyTransformerOptions<Page extends PageData, Meta extends MetaData> {
-    /**
-     * @deprecated use `transformers` instead
-     */
-    attachFile?: (node: Item, file?: PageFile<Page>) => Item;
-    /**
-     * @deprecated use `transformers` instead
-     */
-    attachFolder?: (node: Folder, folder: {
-        children: (PageFile<Page> | MetaFile<Meta>)[];
-    }, meta?: MetaFile<Meta>) => Folder;
-    /**
-     * @deprecated use `transformers` instead
-     */
-    attachSeparator?: (node: Separator) => Separator;
-}
-
 interface PageTreeBuilderContext<Page extends PageData = PageData, Meta extends MetaData = MetaData> {
     /**
      * @internal resolve paths without extensions
      */
     resolveName: (name: string, format: 'meta' | 'page') => string;
-    options: BaseOptions<Page, Meta>;
+    options: BaseOptions;
     transformers: PageTreeTransformer<Page, Meta>[];
-    builder: PageTreeBuilder<Page, Meta>;
+    builder: PageTreeBuilder;
     storage: ContentStorage<Page, Meta>;
     getUrl: UrlFn;
     storages?: Record<string, ContentStorage<Page, Meta>>;
     locale?: string;
     visitedPaths: Set<string>;
 }
-interface PageTreeTransformer<Page extends PageData = any, Meta extends MetaData = any> {
+interface PageTreeTransformer<Page extends PageData = PageData, Meta extends MetaData = MetaData> {
     name?: string;
     file?: (this: PageTreeBuilderContext<Page, Meta>, node: Item, filePath?: string) => Item;
     folder?: (this: PageTreeBuilderContext<Page, Meta>, node: Folder, folderPath: string, metaPath?: string) => Folder;
     separator?: (this: PageTreeBuilderContext<Page, Meta>, node: Separator) => Separator;
     root?: (this: PageTreeBuilderContext<Page, Meta>, node: Root) => Root;
 }
-interface BaseOptions<Page extends PageData = PageData, Meta extends MetaData = MetaData> extends LegacyTransformerOptions<Page, Meta> {
+interface BaseOptions {
+    id?: string;
     /**
      * Remove references to the file path of original nodes (`$ref`)
      *
      * @defaultValue false
      */
     noRef?: boolean;
-    transformers?: PageTreeTransformer<Page, Meta>[];
-    resolveIcon?: (icon: string | undefined) => ReactNode | undefined;
+    plugins?: LoaderPlugin[];
     /**
      * generate fallback page tree
      *
@@ -291,19 +325,17 @@ interface BaseOptions<Page extends PageData = PageData, Meta extends MetaData =
      */
     generateFallback?: boolean;
 }
-interface PageTreeBuilder<Page extends PageData = PageData, Meta extends MetaData = MetaData> {
-    build: (options: BaseOptions<Page, Meta> & {
-        id?: string;
-        storage: ContentStorage<Page, Meta>;
+interface PageTreeBuilder {
+    build: (options: BaseOptions & {
+        storage: ContentStorage;
     }) => Root;
     /**
      * Build page tree and fallback to the default language if the localized page doesn't exist
      */
-    buildI18n: (options: BaseOptions<Page, Meta> & {
-        id?: string;
-        storages: Record<string, ContentStorage<Page, Meta>>;
+    buildI18n: (options: BaseOptions & {
+        storages: Record<string, ContentStorage>;
     }) => Record<string, Root>;
 }
 declare function createPageTreeBuilder(getUrl: UrlFn): PageTreeBuilder;
 
-export { type BaseOptions, type ContentStorage, type FileInfo, FileSystem, type FolderInfo, type InferMetaType, type InferPageType, type LanguageEntry, type LoadOptions, type LoaderConfig, type LoaderOptions, type LoaderOutput, type Meta, type MetaData, type MetaFile, type Page, type PageData, type PageFile, type PageTreeBuilder, type PageTreeBuilderContext, type PageTreeTransformer, type Source, type SourceConfig, type Transformer, type UrlFn, type VirtualFile, createGetUrl, createPageTreeBuilder, getSlugs, loadFiles, loader, parseFilePath, parseFolderPath };
+export { type BaseOptions, type ContentStorage, type FileInfo, FileSystem, type FolderInfo, type InferMetaType, type InferPageType, type LanguageEntry, type LoadOptions, type LoaderConfig, type LoaderOptions, type LoaderOutput, type LoaderPlugin, type LoaderPlugins, type Meta, type MetaData, type MetaFile, type Page, type PageData, type PageFile, type PageTreeBuilder, type PageTreeBuilderContext, type PageTreeTransformer, type Source, type SourceConfig, type Transformer, type UrlFn, type VirtualFile, buildPlugins, createGetUrl, createPageTreeBuilder, getSlugs, loadFiles, loader, parseFilePath, parseFolderPath };

package/dist/source/index.js

@@ -13,36 +13,6 @@ import {
 } from "../chunk-PFNP6PEB.js";
 import "../chunk-JSBRDJBE.js";
 
-// src/source/page-tree/legacy.ts
-function legacyTransformer(transformer) {
-  return {
-    file(node, file) {
-      if (!transformer.attachFile) return node;
-      const content = file ? this.storage.read(file) : void 0;
-      return transformer.attachFile(
-        node,
-        content?.format === "page" ? content : void 0
-      );
-    },
-    folder(node, folderPath, metaPath) {
-      if (!transformer.attachFolder) return node;
-      const files = this.storage.readDir(folderPath) ?? [];
-      const meta = metaPath ? this.storage.read(metaPath) : void 0;
-      return transformer.attachFolder(
-        node,
-        {
-          children: files.flatMap((file) => this.storage.read(file) ?? [])
-        },
-        meta?.format === "meta" ? meta : void 0
-      );
-    },
-    separator(node) {
-      if (!transformer.attachSeparator) return node;
-      return transformer.attachSeparator(node);
-    }
-  };
-}
-
 // src/source/page-tree/transformer-fallback.ts
 function transformerFallback() {
   const addedFiles = /* @__PURE__ */ new Set();
@@ -105,13 +75,13 @@ function buildAll(paths, ctx, reversed = false) {
 }
 function resolveFolderItem(folderPath, item, ctx, idx) {
   if (item === rest || item === restReversed) return item;
-  const { options, resolveName } = ctx;
+  const { resolveName } = ctx;
   let match = separator.exec(item);
   if (match?.groups) {
     let node = {
       $id: `${folderPath}#${idx}`,
       type: "separator",
-      icon: options.resolveIcon?.(match.groups.icon),
+      icon: match.groups.icon,
       name: match.groups.name
     };
     for (const transformer of ctx.transformers) {
@@ -126,7 +96,7 @@ function resolveFolderItem(folderPath, item, ctx, idx) {
     const isRelative = url.startsWith("/") || url.startsWith("#") || url.startsWith(".");
     let node = {
       type: "page",
-      icon: options.resolveIcon?.(icon),
+      icon,
       name,
       url,
       external: !isRelative
@@ -203,7 +173,7 @@ function buildFolderNode(folderPath, isGlobalRoot, ctx) {
   let node = {
     type: "folder",
     name,
-    icon: options.resolveIcon?.(meta?.data.icon) ?? index?.icon,
+    icon: meta?.data.icon ?? index?.icon,
     root: meta?.data.root,
     defaultOpen: meta?.data.defaultOpen,
     description: meta?.data.description,
@@ -230,7 +200,7 @@ function buildFileNode(path, ctx) {
     type: "page",
     name: title ?? pathToName(basename(path, extname(path))),
     description,
-    icon: options.resolveIcon?.(icon),
+    icon,
     url: getUrl(page.slugs, locale),
     $ref: !options.noRef ? {
       file: path
@@ -257,9 +227,9 @@ function build(id, ctx) {
 }
 function createPageTreeBuilder(getUrl) {
   function getTransformers(options, generateFallback) {
-    const transformers = [legacyTransformer(options)];
-    if (options.transformers) {
-      transformers.push(...options.transformers);
+    const transformers = [];
+    for (const plugin of options.plugins ?? []) {
+      if (plugin.transformPageTree) transformers.push(plugin.transformPageTree);
     }
     if (generateFallback) {
       transformers.push(transformerFallback());
@@ -401,7 +371,7 @@ var parsers = {
   }
 };
 function loadFiles(files, options, i18n) {
-  const { buildFile, transformers = [] } = options;
+  const { buildFile, plugins = [] } = options;
   const parser = parsers[i18n.parser ?? "dot"];
   const storages = {};
   const normalized = files.map(
@@ -424,11 +394,11 @@ function loadFiles(files, options, i18n) {
       const [path, locale = i18n.defaultLanguage] = parser(item.path);
       if (locale === lang) storage.write(path, item);
     }
-    for (const transformer of transformers) {
-      transformer({
-        storage,
-        options
-      });
+    const context = {
+      storage
+    };
+    for (const plugin of plugins) {
+      plugin.transformStorage?.(context);
     }
     storages[lang] = storage;
   }
@@ -442,6 +412,114 @@ function normalizePath(path) {
   return segments.join("/");
 }
 
+// src/source/plugins/index.ts
+function buildPlugins(plugins) {
+  return plugins;
+}
+
+// src/source/plugins/slugs.ts
+function slugsPlugin(slugsFn) {
+  function isIndex(file) {
+    return basename(file, extname(file)) === "index";
+  }
+  return {
+    transformStorage({ storage }) {
+      const indexFiles = /* @__PURE__ */ new Set();
+      const taken = /* @__PURE__ */ new Set();
+      const autoIndex = slugsFn === void 0;
+      for (const path of storage.getFiles()) {
+        const file = storage.read(path);
+        if (!file || file.format !== "page" || file.slugs) continue;
+        if (isIndex(path) && autoIndex) {
+          indexFiles.add(path);
+          continue;
+        }
+        file.slugs = slugsFn ? slugsFn(parseFilePath(path)) : getSlugs(path);
+        const key = file.slugs.join("/");
+        if (taken.has(key)) throw new Error("Duplicated slugs");
+        taken.add(key);
+      }
+      for (const path of indexFiles) {
+        const file = storage.read(path);
+        if (file?.format !== "page") continue;
+        file.slugs = getSlugs(path);
+        if (taken.has(file.slugs.join("/"))) file.slugs.push("index");
+      }
+    }
+  };
+}
+
+// src/source/plugins/compat.ts
+function compatPlugin(loader2, {
+  attachFile,
+  attachSeparator,
+  attachFolder,
+  transformers
+}) {
+  const chunk = [];
+  chunk.push({
+    transformPageTree: {
+      file(node, file) {
+        if (!attachFile) return node;
+        const content = file ? this.storage.read(file) : void 0;
+        return attachFile(
+          node,
+          content?.format === "page" ? content : void 0
+        );
+      },
+      folder(node, folderPath, metaPath) {
+        if (!attachFolder) return node;
+        const files = this.storage.readDir(folderPath) ?? [];
+        const meta = metaPath ? this.storage.read(metaPath) : void 0;
+        return attachFolder(
+          node,
+          {
+            children: files.flatMap((file) => this.storage.read(file) ?? [])
+          },
+          meta?.format === "meta" ? meta : void 0
+        );
+      },
+      separator(node) {
+        if (!attachSeparator) return node;
+        return attachSeparator(node);
+      }
+    }
+  });
+  for (const transformer of loader2.transformers ?? []) {
+    chunk.push(fromStorageTransformer(transformer));
+  }
+  for (const transformer of transformers ?? []) {
+    chunk.push(fromPageTreeTransformer(transformer));
+  }
+  return chunk;
+}
+function fromPageTreeTransformer(transformer) {
+  return {
+    transformPageTree: transformer
+  };
+}
+function fromStorageTransformer(transformer) {
+  return {
+    transformStorage: transformer
+  };
+}
+
+// src/source/plugins/icon.ts
+function iconPlugin(resolveIcon) {
+  function replaceIcon(node) {
+    if (node.icon === void 0 || typeof node.icon === "string")
+      node.icon = resolveIcon(node.icon);
+    return node;
+  }
+  return {
+    transformPageTree: {
+      file: replaceIcon,
+      folder: replaceIcon,
+      separator: replaceIcon
+    }
+  };
+}
+
 // src/source/loader.ts
 function indexPages(storages, getUrl) {
   const result = {
@@ -500,40 +578,20 @@ function createOutput(options) {
   if (!options.url && !options.baseUrl) {
     console.warn("`loader()` now requires a `baseUrl` option to be defined.");
   }
-  const {
-    source,
-    baseUrl = "/",
-    i18n,
-    slugs: slugsFn,
-    url: urlFn,
-    transformers = []
-  } = options;
+  const { source, baseUrl = "/", i18n, slugs: slugsFn, url: urlFn } = options;
   const getUrl = urlFn ? (...args) => normalizeUrl(urlFn(...args)) : createGetUrl(baseUrl, i18n);
   const defaultLanguage = i18n?.defaultLanguage ?? "";
   const files = loadSource(source);
-  const transformerSlugs = ({ storage }) => {
-    const indexFiles = /* @__PURE__ */ new Set();
-    const taken = /* @__PURE__ */ new Set();
-    const autoIndex = slugsFn === void 0;
-    for (const path of storage.getFiles()) {
-      const file = storage.read(path);
-      if (!file || file.format !== "page" || file.slugs) continue;
-      if (isIndex(path) && autoIndex) {
-        indexFiles.add(path);
-        continue;
-      }
-      file.slugs = slugsFn ? slugsFn(parseFilePath(path)) : getSlugs(path);
-      const key = file.slugs.join("/");
-      if (taken.has(key)) throw new Error("Duplicated slugs");
-      taken.add(key);
-    }
-    for (const path of indexFiles) {
-      const file = storage.read(path);
-      if (file?.format !== "page") continue;
-      file.slugs = getSlugs(path);
-      if (taken.has(file.slugs.join("/"))) file.slugs.push("index");
-    }
-  };
+  const plugins = [slugsPlugin(slugsFn)];
+  if (options.icon) {
+    plugins.push(iconPlugin(options.icon));
+  }
+  if (options.plugins) {
+    plugins.push(...buildPlugins(options.plugins));
+  }
+  if (options.pageTree) {
+    plugins.push(...compatPlugin(options, options.pageTree));
+  }
   const storages = loadFiles(
     files,
     {
@@ -554,7 +612,7 @@ function createOutput(options) {
           data: file.data
         };
       },
-      transformers: [transformerSlugs, ...transformers]
+      plugins
     },
     i18n ?? {
       defaultLanguage,
@@ -570,7 +628,7 @@ function createOutput(options) {
     get pageTree() {
       pageTree ??= builder.buildI18n({
         storages,
-        resolveIcon: options.icon,
+        plugins,
         ...options.pageTree
       });
       return i18n ? pageTree : pageTree[defaultLanguage];
@@ -599,10 +657,12 @@ function createOutput(options) {
           hash
         };
     },
-    getPages(language = defaultLanguage) {
+    getPages(language) {
       const pages = [];
       for (const [key, value] of walker.pages.entries()) {
-        if (key.startsWith(`${language}.`)) pages.push(value);
+        if (language === void 0 || key.startsWith(`${language}.`)) {
+          pages.push(value);
+        }
       }
       return pages;
     },
@@ -676,9 +736,6 @@ function fileToPage(file, getUrl, locale) {
   };
 }
 var GroupRegex = /^\(.+\)$/;
-function isIndex(file) {
-  return basename(file, extname(file)) === "index";
-}
 function getSlugs(file) {
   if (typeof file !== "string") return getSlugs(file.path);
   const dir = dirname(file);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-core",
-  "version": "15.8.0",
+  "version": "15.8.1",
   "description": "The library for building a documentation website in Next.js",
   "keywords": [
     "NextJs",
@@ -114,21 +114,21 @@
   },
   "devDependencies": {
     "@mdx-js/mdx": "^3.1.1",
-    "@mixedbread/sdk": "^0.28.1",
+    "@mixedbread/sdk": "^0.29.0",
     "@oramacloud/client": "^2.1.4",
-    "@tanstack/react-router": "^1.132.2",
+    "@tanstack/react-router": "^1.132.7",
     "@types/estree-jsx": "^1.0.5",
     "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.3",
     "@types/negotiator": "^0.6.4",
     "@types/node": "24.5.2",
-    "@types/react": "^19.1.13",
+    "@types/react": "^19.1.14",
     "@types/react-dom": "^19.1.9",
-    "algoliasearch": "5.37.0",
+    "algoliasearch": "5.39.0",
     "mdast-util-mdx-jsx": "^3.2.0",
     "mdast-util-mdxjs-esm": "^2.0.1",
     "next": "^15.5.4",
-    "react-router": "^7.9.1",
+    "react-router": "^7.9.3",
     "remark-mdx": "^3.1.1",
     "remove-markdown": "^0.6.2",
     "typescript": "^5.9.2",