Bundler Plugins

Copyexport type MDXBundlerPresetOptions = Omit<
  NonNullable<ProcessorOptions>,
  'rehypePlugins' | 'remarkPlugins'
> & {
  rehypePlugins?: ResolvePlugins;
  remarkPlugins?: ResolvePlugins;
 
  /** @private for `remark-include` */
  _include?: Pluggable;
  remarkStructureOptions?: Plugins.StructureOptions | false;
  remarkHeadingOptions?: Plugins.RemarkHeadingOptions | false;
  remarkImageOptions?: Plugins.RemarkImageOptions | false;
  remarkCodeTabOptions?: Plugins.RemarkCodeTabOptions | false;
  remarkNpmOptions?: Plugins.RemarkNpmOptions | false;
  rehypeCodeOptions?: Plugins.RehypeCodeOptions | false;
};

Copyexport async function mdxPreset(options: MDXBundlerPresetOptions = {}): Promise<ProcessorOptions> {
  const {
    rehypeCodeOptions,
    remarkImageOptions,
    remarkHeadingOptions,
    remarkStructureOptions,
    remarkCodeTabOptions,
    remarkNpmOptions,
    _include,
    ...mdxOptions
  } = options;

Copyconst remarkPlugins = await resolvePlugins(
  (v) => [
    import('remark-gfm').then((mod) => mod.default),
    remarkHeadingOptions !== false &&
      import('@/mdx-plugins/remark-heading').then((mod) => [
        mod.remarkHeading,
        {
          generateToc: false,
          ...remarkHeadingOptions,
        },
      ]),
    _include ?? false,
    remarkImageOptions !== false &&
      import('@/mdx-plugins/remark-image').then((mod) => [
        mod.remarkImage,
        {
          ...remarkImageOptions,
          useImport: remarkImageOptions?.useImport ?? true,
        },
      ]),
    remarkCodeTabOptions !== false &&
      import('@/mdx-plugins/remark-code-tab').then((mod) => [
        mod.remarkCodeTab,
        remarkCodeTabOptions,
      ]),
    remarkNpmOptions !== false &&
      import('@/mdx-plugins/remark-npm').then((mod) => [mod.remarkNpm, remarkNpmOptions]),
    ...v,
    remarkStructureOptions !== false &&
      import('@/mdx-plugins/remark-structure').then((mod) => [
        mod.remarkStructure,
        {
          exportAs: 'structuredData',
          ...remarkStructureOptions,
        } satisfies Plugins.StructureOptions,
      ]),
  ],
  mdxOptions.remarkPlugins,
);

Copyconst rehypePlugins = await resolvePlugins(
  (v) => [
    rehypeCodeOptions !== false &&
      import('@/mdx-plugins/rehype-code').then((mod) => [mod.rehypeCode, rehypeCodeOptions]),
    ...v,
    import('@/mdx-plugins/rehype-toc').then((mod) => mod.rehypeToc),
  ],
  mdxOptions.rehypePlugins,
);

Copyexport function createMDX(createOptions: CreateMDXOptions = {}) {
  const core = createNextCore(applyDefaults(createOptions));

Copyfunction createNextCore(options: Required<CreateMDXOptions>): Core {
  return createCore({
    environment: 'next',
    outDir: options.outDir,
    configPath: options.configPath,
    plugins: [options.index && indexFile(options.index)],
  });

Copyexport default function indexFile(options: IndexFilePluginOptions = {}): Plugin {
  const { target = 'default', addJsExtension, browser = true, dynamic = true } = options;
  let dynamicCollections: CollectionItem[];
 
  function isDynamic(collection: CollectionItem) {
    return (
      (collection.type === 'docs' && collection.docs.dynamic) ||
      (collection.type === 'doc' && collection.dynamic)
    );
  }
 
  function generateConfigs(core: Core): {
    serverOptions: ServerOptions;
    tc: string;
  } {
    const serverOptions: ServerOptions = {};
    const typeConfigs: string[] = ['import("fumadocs-mdx/runtime/types").InternalTypeConfig'];
    const ctx = core.getPluginContext();
 
    for (const plugin of core.getPlugins()) {
      const indexFilePlugin = plugin['index-file'];
      if (!indexFilePlugin) continue;
 
      indexFilePlugin.serverOptions?.call(ctx, serverOptions);
      const config = indexFilePlugin.generateTypeConfig?.call(ctx);
      if (config) typeConfigs.push(config);
    }
 
    return {
      serverOptions,
      tc: typeConfigs.join(' & '),
    };
  }

Copyexport interface IndexFilePluginOptions {
  target?: 'default' | 'vite';
 
  /**
   * add `.js` extensions to imports, needed for ESM without bundler resolution
   */
  addJsExtension?: boolean;
 
  /**
   * Generate entry point for browser
   * @defaultValue true
   */
  browser?: boolean;
 
  /**
   * Generate entry point for dynamic compilation
   * @defaultValue true
   */
  dynamic?: boolean;
}

Copyconst loader: LoaderDefinitionFunction<WebpackLoaderOptions> = function loader(source) {
  const callback = this.async();
  const options = this.getOptions();
  this.cacheable(true);
  this.addDependency(options.absoluteCompiledConfigPath);
 
  if (!instance) {
    instance = toWebpack(
      createMdxLoader(
        createStandaloneConfigLoader({
          core: getCore(options),
          buildConfig: false,
          mode: options.isDev ? 'dev' : 'production',
        }),
      ),
    );
  }
 
  void instance.call(this, source, callback);
};

Copyconst loader: LoaderDefinitionFunction<WebpackLoaderOptions> = function (source) {
  const callback = this.async();
  const options = this.getOptions();
  this.cacheable(true);
  this.addDependency(options.absoluteCompiledConfigPath);
 
  if (!instance) {
    instance = toWebpack(
      createMetaLoader(
        createStandaloneConfigLoader({
          core: getCore(options),
          buildConfig: false,
          mode: options.isDev ? 'dev' : 'production',
        }),
        {
          json: 'json',
          yaml: 'js',
        },
      ),
    );
  }
 
  void instance.call(this, source, callback);
};

Copyexport interface StoryLoaderOptions {
  /**
   * Path to `tsconfig.json`.
   *
   * @default "tsconfig.json"
   */
  tsconfigPath?: string;
}
 
let projectPromise: Promise<Project> | undefined;
 
const loader: LoaderDefinitionFunction<StoryLoaderOptions> = function (source) {
  const callback = this.async();
  const options = this.getOptions();
  this.cacheable(true);
 
  const run = async () => {
    if (!projectPromise) {
      const resolvedTsconfig = options.tsconfigPath ?? path.join(this.rootContext, 'tsconfig.json');
      projectPromise = createControlsProject(resolvedTsconfig);
    }
 
    try {
      const transformed = transformStoryFile(
        '@fumadocs/story/next/client',
        source,
        this.resourcePath,
        await projectPromise!,
      );
      callback(undefined, transformed ?? source);
    } catch (error) {
      if (!(error instanceof Error)) throw error;
      callback(error);
    }
  };
 
  void run();
};

Copyexport interface PluginOptions {
  /**
   * Generate index files for accessing content.
   *
   * @defaultValue true
   */
  index?: boolean | IndexFilePluginOptions;
 
  /**
   * @defaultValue source.config.ts
   */
  configPath?: string;
 
  /**
   * Update Vite config to fix module resolution of Fumadocs
   *
   * @defaultValue true
   */
  updateViteConfig?: boolean;
 
  /**
   * Output directory of generated files
   *
   * @defaultValue '.source'
   */
  outDir?: string;
}

Copyreturn [
  {
    name: 'fumadocs-mdx',
    async config(config) {
      root = config.root ?? process.cwd();
      options = applyDefaults(root, pluginOptions);
      core = createViteCore(options);
      await core.init({
        config: buildConfig(
          forcedConfig
            ? await forcedConfig
            : (await runnerImport<Record<string, unknown>>(options.configPath)).module,
          root,
        ),
      });
 
      const configLoader = createIntegratedConfigLoader(core);
      const mdxLoader = toVite(createMdxLoader(configLoader));
      const metaLoader = toVite(
        createMetaLoader(configLoader, {
          // vite has built-in plugin for JSON files
          json: 'json',
        }),
      );
 
      mdxPlugin.transform = {
        filter: mdxLoader.filter,
        order: 'pre',
        handler(code, id) {
          // Vite RSC will pass the compiled MDX file's client module with ID `virtual:vite-rsc/client-references/group/facade:xxx.mdx`.
          // The format of `value` becomes JavaScript, which will break the MDX compiler.
          // We have to ignore them.
          if (id.includes('virtual:vite-rsc')) return null;
          if (!forcedConfig) this.addWatchFile(options.configPath);
          return mdxLoader.transform.call(this, code, id);
        },
      };
      metaPlugin.transform = {
        filter: metaLoader.filter,
        order: 'pre',
        handler(code, id) {
          if (!forcedConfig) this.addWatchFile(options.configPath);
          return metaLoader.transform.call(this, code, id);
        },
      };
 
      if ('_fumadocs_skipViteConfig' in config && config._fumadocs_skipViteConfig) return;
      if (!options.updateViteConfig) return;
 
      const { getConfig } = await import('@fumadocs/vite');
      return getConfig({ root });
    },

Copyexport interface PluginOptions {
  configPath?: string;
  outDir?: string;
}
 
export default async function mdx(
  config: Record<string, unknown> | Promise<Record<string, unknown>>,
  options?: PluginOptions,
): Promise<RolldownPlugin[]> {
  const core = createCore({
    configPath: options?.configPath ?? _Defaults.configPath,
    outDir: options?.outDir ?? _Defaults.outDir,
    environment: 'rolldown',
  });
  await core.init({
    config: buildConfig(await config, process.cwd()),
  });
 
  const configLoader = createIntegratedConfigLoader(core);
  const mdxLoader = toVite(createMdxLoader(configLoader));
  const metaLoader = toVite(
    createMetaLoader(configLoader, {
      // rolldown has built-in plugin for JSON files
      json: 'json',
    }),
  );
 

Copyreturn [
  {
    name: 'fumadocs-mdx',
    load: {
      filter: { id: [metaLoaderGlob, mdxLoaderGlob] },
      // Rolldown couldn't read the correct file path when query params exist.
      async handler(id) {
        const idx = id.lastIndexOf('?');
        if (idx === -1) return null;
 
        return fs.readFile(id.slice(0, idx), 'utf-8');
      },
    },
  },
  {
    name: 'fumadocs-mdx:mdx',
    transform: {
      filter: mdxLoader.filter,
      handler: mdxLoader.transform,
    },
  },
  {
    name: 'fumadocs-mdx:meta',
    transform: {
      filter: metaLoader.filter,
      handler: metaLoader.transform,
    },
  },
];

Copyexport interface StoryPluginOptions {
  /**
   * Path to `tsconfig.json`.
   *
   * @default "tsconfig.json"
   */
  tsconfigPath?: string;
 
  /**
   * Filter story files to transform by id (regex)
   *
   * @default `/\.story\.(js|jsx|ts|tsx)$/`
   */
  filter?: RegExp;
}

Copyexport default function story(pluginOptions: StoryPluginOptions = {}): Plugin {
  const { filter = /\.story\.(js|jsx|ts|tsx)$/ } = pluginOptions;
  let tsconfigPath: string;
  let projectPromise: Promise<Project> | undefined;
 
  return {
    name: 'fumadocs:story',
    enforce: 'pre',
    configResolved(resolved) {
      tsconfigPath = pluginOptions.tsconfigPath ?? path.join(resolved.root, 'tsconfig.json');
    },
    transform: {
      filter: { id: filter },
      async handler(code, id) {
        projectPromise ??= createControlsProject(tsconfigPath);
 
        return transformStoryFile('@fumadocs/story/vite/client', code, id, await projectPromise);
      },
    },
  };

Copy  return {
    name: 'bun-plugin-fumadocs-mdx',
    async setup(build) {
      const importPath = pathToFileURL(configPath).href;
      const core = createCore({
        environment,
        outDir,
        configPath,
      });
 
      await core.init({
        config: buildConfig(await import(importPath), process.cwd()),
      });
 
      const configLoader = createIntegratedConfigLoader(core);
      toBun(createMdxLoader(configLoader))(build);
      if (!disableMetaFile) toBun(createMetaLoader(configLoader))(build);
    },
  };
}

Copyexport const initialize: InitializeHook<NodeLoaderOptions> = (options) => {
  const core = createCore({
    environment: 'node-loader',
    ...options,
    configPath: options.configPath ?? _Defaults.configPath,
    outDir: options.outDir ?? _Defaults.outDir,
  });
 
  const configLoader = createStandaloneConfigLoader({
    core,
    buildConfig: true,
    mode: 'production',
  });
 
  cachedLoaders = [toNode(createMdxLoader(configLoader))];
  if (!options.disableMetaFile) {
    cachedLoaders.push(toNode(createMetaLoader(configLoader)));
  }
};
 

Copyexport const load: LoadHook = async (url, context, nextLoad) => {
  if (!cachedLoaders) throw new Error('not initialized');
  const hooks = cachedLoaders;
 
  function run(
    i: number,
    url: string,
    context: LoadHookContext,
  ): LoadFnOutput | Promise<LoadFnOutput> {
    if (i >= hooks.length) {
      return nextLoad(url, context);
    }
 
    return hooks[i](url, context, (url, ctx) => run(i + 1, url, { ...context, ...ctx }));
  }
 
  return run(0, url, context);
};