Quick Start

Copyconst dirShortcuts: Record<string, string> = {
  ':preview': 'https://preview.fumadocs.dev/registry',
  ':dev': 'http://localhost:3000/registry',
};

Copyfunction createClientFromDir(dir = 'https://fumadocs.dev/registry') {
  if (dir in dirShortcuts) dir = dirShortcuts[dir];
 
  return dir.startsWith('http://') || dir.startsWith('https://')
    ? new HttpRegistryConnector(dir)
    : new LocalRegistryConnector(dir);
}

Copyexport interface DocsCollectionConfig<
  FrontmatterSchema extends StandardSchemaV1 | undefined,
  MetaSchema extends StandardSchemaV1 | undefined,
> {
  dir: string;
  docs: Omit<DocsMDXCollectionConfig<FrontmatterSchema>, 'dir'>;
  meta: Omit<DataCollectionConfig<MetaSchema>, 'dir'>;
}
 
export function docsCollection<
  FrontmatterSchema extends StandardSchemaV1 | typeof pageSchema = typeof pageSchema,
  MetaSchema extends StandardSchemaV1 | typeof metaSchema = typeof metaSchema,
>(config: DocsCollectionConfig<FrontmatterSchema, MetaSchema>) {
  return {
    index: new DocsCollection(),
    meta: dataCollection({ dir: config.dir, ...config.meta }),
    doc: docsMdxCollection({ dir: config.dir, ...config.docs }),
  };
}

Copyexport class DocsCollection extends Collection {
  constructor() {
    super();
    this.onEmit.pipe(async (data, ctx) => {
      const file = await ctx.createCodeGenerator(`${this.name}.ts`, ({ codegen }) => {
        const docName = `${this.name}$doc`;
        const metaName = `${this.name}$meta`;
        codegen.addNamedImport([docName], `./${docName}`);
        codegen.addNamedImport([metaName], `./${metaName}`);
        codegen.addNamedImport(['docsStore'], '@fumadocs/content/runtime');
        codegen.push(`export const ${this.name} = docsStore(${docName}, ${metaName})`);
      });
      data.push(file);
      return data;
    });
  }

Copyexport function docsMdxCollection<
  FrontmatterSchema extends StandardSchemaV1 | typeof pageSchema = typeof pageSchema,
>(config: DocsMDXCollectionConfig<FrontmatterSchema>) {
  const { options = {}, frontmatter = pageSchema, ...rest } = config;
 
  return mdxCollection<FrontmatterSchema>({
    ...rest,
    frontmatter: frontmatter as never,
    async options() {
      const mdxOptions = typeof options === 'object' ? options : await options();
      const { remarkInclude } = await import('fuma-content/plugins/remark/include');
      return mdxPreset({
        ...mdxOptions,
        _include: remarkInclude,
      });
    },
  });
}

Copyexport function toFumadocsSource<
  Mdx extends MDXStoreData<PageData> | MDXStoreLazyData<PageData, unknown> = MDXStoreData<
    PageData,
    unknown
  >,
  Meta extends { data: MetaData } = { data: MetaData },
>(mdxStore?: FileCollectionStore<Mdx>, metaStore?: FileCollectionStore<Meta>) {
  const out: StaticSource<{
    pageData: ToPageData<Mdx>;
    metaData: Meta['data'];
  }> = { files: [] };
  for (const page of mdxStore?.list() ?? []) {
    out.files.push({
      type: 'page',
      data: ('compiled' in page
        ? { ...page, ...page.compiled.frontmatter }
        : { ...page, ...page.frontmatter }) as unknown as ToPageData<Mdx>,
      path: page.path,
      absolutePath: page.fullPath,
    });
  }
  for (const file of metaStore?.list() ?? []) {
    out.files.push({
      type: 'meta',
      data: file.data,
      path: file.path,
      absolutePath: file.fullPath,
    });
  }
  return out;
}

Copyexport default async function DocPage({ slugs }: PageProps<'/docs/[...slugs]'>) {
  const config = await getConfigRuntime();
  const source = await getSource(config);
  const page = source.getPage(slugs);
  const mdPreset = config.layout.presets?.md ?? 'docs';
  let mdPresetComponents: MdPresetComponents;
 
  if (mdPreset === 'docs') {
    mdPresetComponents = {
      layout: await import('fumadocs-ui/layouts/docs'),
      page: await import('fumadocs-ui/layouts/docs/page'),
    };
  } else {
    mdPresetComponents = {
      layout: await import('fumadocs-ui/layouts/flux'),
      page: await import('fumadocs-ui/layouts/flux/page'),
    };
  }
 
  return <MdContent slugs={slugs} page={page} components={mdPresetComponents} />;
}

Copyasync function MdContent({
  slugs,
  page,
  components,
}: {
  slugs: string[];
  page?: SourcePage;
  components: MdPresetComponents;
}) {
  const config = await getConfigRuntime();
  const source = await getSource(config);
  const layout = layoutConfig(config);
  const { DocsLayout } = components.layout;
  const { DocsBody, DocsTitle, DocsPage, DocsDescription } = components.page;
 
  async function renderContainer(children: ReactNode) {
    const hasAI = await isAISupported();
    return (
      <DocsLayout {...await layout.docs()}>
        {hasAI && (
          <AISearch>
            <AISearchPanel />
            <AISearchTrigger
              position="float"
              className={cn(
                buttonVariants({
                  variant: 'secondary',
                  className: 'text-fd-muted-foreground rounded-2xl',
                }),
              )}
            >
              <MessageCircleIcon className="size-4.5" />
              Ask AI
            </AISearchTrigger>
          </AISearch>
        )}
 
        {children}
      </DocsLayout>
    );
  }

Copyconst compiler = createMarkdownCompiler({
  remarkPlugins: [
    remarkGfm,
    remarkMath,
    remarkMdxMermaid,
    plugin(remarkHeading, { generateToc: false }),
    plugin(remarkNpm, { persist: { id: 'package-manager' } }),
    remarkCodeTab,
  ],
  remarkRehypeOptions: {
    passThrough: ['mdxJsxFlowElement', 'mdxJsxTextElement'],
  },
  rehypePlugins: [
    rehypeKatex,
    plugin(rehypeCode, { lazy: true, fallbackLanguage: 'text' }),
    plugin(rehypeToc, { exportToc: { as: 'data' } }),
  ],
});

Copyprogram
  .command('init')
  .description('create configuration file')
  .action(async () => {
    if ((await findConfigPath()) === null) {
      await fs.writeFile(
        'fumadocs.config.ts',
        `import { defineConfig } from "fumadocs-preview/config";\n\nexport default defineConfig();`,
      );
 
      console.log('note: make sure to install `fumadocs-preview` as a dev dependency too.');
    }
  });
 
program
  .command('start', { isDefault: true })
  .description('start Fumapress')
  .argument('[dirs...]', 'a list of content directories to view')
  .option('-p, --port <PORT>')
  .option('-h, --host <HOST>')
  .action(async (dirs: string[] | undefined, options: { port?: string; host?: string }) => {
    await runStart({ ...options, dirs });
  });

Copyasync function getFreePort(startPort: number): Promise<number> {
  for (let port = startPort; ; port++) {
    try {
      await new Promise<void>((resolve, reject) => {
        const srv = net
          .createServer()
          .once('error', reject)
          .once('listening', () => srv.close(() => resolve()))
          .listen(port);
      });
      return port;
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code !== 'EADDRINUSE') {
        throw err;
      }
    }
  }
}

Copy  if (host) {
    process.env.HOST = host;
  }
  process.env.PORT = String(port);
  process.env.ROOT_DIR = process.cwd();
  if (!dirs || dirs.length === 0) {
    dirs = [''];
  }
  process.env.DEFAULT_PROJECT_DIR = JSON.stringify(dirs.map((v) => path.resolve(v)));
  process.env.HOT_RELOAD = '1';
  process.chdir(baseDir);
  await import(serveFileUrl);
 
  console.log(`ready: Listening on http://${host || 'localhost'}:${port}/`);
}

Copyexport interface LocalMarkdownConfig<
  FrontmatterSchema extends StandardSchemaV1,
  MetaSchema extends StandardSchemaV1,
> extends MarkdownCompilerOptions {
  /**
   * root directory for content files.
   */
  dir: string;
  /**
   * a list of glob patterns, customize the content files to be scanned.
   */
  include?: string[];
  rendererOptions?: Pick<MarkdownRendererASTOptions, 'executor'>;
 
  frontmatterSchema?: FrontmatterSchema;
  metaSchema?: MetaSchema;
}

Copyasync load() {
  let promise = compilerCache.get(page);
  if (!promise) {
    promise = compiler.compile({
      path: page.absolutePath,
      value: page.content,
      data: { frontmatter: page.frontmatter },
    });
  }
 
  const res = await promise;
  return res.type === 'ast'
    ? fromAst({
        tree: res.tree,
        filePath: res.file.path,
        rehypeToc: res.file.data.rehypeToc,
        structuredData: res.file.data.structuredData,
        ...config.rendererOptions,
      })
    : fromJS({
        code: res.code,
        filePath: res.file.path,
        baseUrl: pathToFileURL(res.file.path).href,
        structuredData: res.file.data.structuredData,
      });
},

Copyasync devServer(url = getDevServerUrlFromEnv()) {
  if (!url) {
    console.warn(
      `[@fumadocs/local-md] dev server URL could not be found, try passing the URL to devServer() explicitly instead`,
    );
    return;
  }
 
  const { connectDevServer } = await import('@/dev/node-client');
  const conn = connectDevServer(url);
  conn.send({
    type: 'watch-dir',
    dir: path.resolve(config.dir),
    includes: config.include ?? defaultInclude,
  });
 
  conn.subscribe((event) => {
    if (event.type === 'change') {
      this.invalidateFile(event.absolutePath);
    }
  });
},

Copyexport function DevClient(): ReactNode {
  const router = useRouter();
 
  const onUpdate = useEffectEvent((event: DevServerEvent) => {
    if (event.type === 'change') {
      console.log(`[@fumadocs/local-md] "${event.absolutePath}" updated`);
      router.refresh();
    }
  });
 
  useEffect(() => {
    const url = getDevServerUrlFromEnv();
    if (!url) return;
 
    const ws = new WebSocket(url);
    ws.onopen = () => {
      console.log(`[@fumadocs/local-md] connected to dev server at ${url}`);
    };
 
    ws.onmessage = (event) => {
      const decoded = decodeDevEvent(String(event.data));
      if (decoded) onUpdate(decoded);
    };
 
    ws.onclose = () => {
      console.log(`[@fumadocs/local-md] disconnected from dev server at ${url}`);
    };
 
    return () => {
      ws.close();
    };
  }, []);