Fumadocs Headless

Fumadocs Headless Usage Guide

The Headless component library provides the core functionality needed to build documentation sites.

Navigation Components

Breadcrumb Navigation

'use client';
import { useBreadcrumb } from 'fumadocs-core/breadcrumb';
import { usePathname } from 'next/navigation';
import { Fragment } from 'react';
import { ChevronRight } from 'lucide-react';
import Link from 'next/link';

export function Breadcrumb({ tree }: { tree: any }) {
  const pathname = usePathname();
  const items = useBreadcrumb(pathname, tree);

  if (items.length === 0) return null;

  return (
    <div className="flex items-center gap-1 text-sm font-medium text-fd-muted-foreground">
      {items.map((item, i) => (
        <Fragment key={i}>
          {i !== 0 && <ChevronRight className="size-4 shrink-0 rtl:rotate-180" />}
          {item.url ? (
            <Link href={item.url} className="truncate hover:text-fd-accent-foreground">
              {item.name}
            </Link>
          ) : (
            <span className="truncate">{item.name}</span>
          )}
        </Fragment>
      ))}
    </div>
  );
}

Link Component

Smart link component that automatically handles external links and internal routing.

import { Link } from 'fumadocs-core/components/link';

<Link href="/docs/page">Link Text</Link>

TOC (Table of Contents)

import { getTOC } from 'fumadocs-core/utils';
import { Text } from 'fumadocs-ui/components/text';

const toc = await getTOC(markdownContent);

Content Collections API

Define Content Sources

Create source.ts or loader.ts:

import { defineDocs } from 'fumadocs-mdx/config';
import { pageSchema, metaSchema } from 'fumadocs-core/source/schema';
import { z } from 'zod';

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    schema: pageSchema.extend({
      index: z.boolean().default(false),
      tags: z.array(z.string()).default([]),
      category: z.string(),
    }),
  },
  meta: {
    schema: metaSchema.extend({
      title: z.string(),
      description: z.string(),
    }),
  },
});

export const loader = async (files: Awaited<ReturnType<typeof defineDocs>>) => ({
  ...docs(files),
});

Access Content

import { source } from '@/lib/source';

// Get all pages
const pages = source.getPageList();

// Get specific page
const page = source.getPage('/docs/guide');

// Get page tree
const tree = source.getPageTree();

// Get paginated list with filtering
const pages = source.getPageList({ filter: p => p.data.published });

Search Integration

Orama (Default)

// search.server.ts
import { OramaSearch } from 'fumadocs-core/search/orama';

export const search = new OramaSearch({
  location: 'server',
});

Static Mode

import { create } from '@orama/orama';

function initOrama() {
  return create({
    schema: { _: 'string' },
    language: 'english',
  });
}

export const search = new OramaSearch({
  location: 'static',
  initOrama,
});

Custom Schema

function initOrama() {
  return create({
    schema: {
      title: 'string',
      url: 'string',
      tags: 'string[]',
      content: 'string',
    },
    language: 'english',
  });
}

export const search = new OramaSearch({
  location: 'static',
  initOrama,
});

Algolia

import { AlgoliaSearch } from 'fumadocs-core/search/algolia';

export const search = new AlgoliaSearch({
  appId: process.env.ALGOLIA_APP_ID!,
  apiKey: process.env.ALGOLIA_API_KEY!,
});

Mixedbread

import { MixedbreadSearch } from 'fumadocs-core/search/mixedbread';

export const search = new MixedbreadSearch({
  apiKey: process.env.MIXEDBREAD_API_KEY!,
});

Trieve

import { TrieveSearch } from 'fumadocs-core/search/trieve';

export const search = new TrieveSearch({
  client: {
    apiKey: process.env.TRIEVE_API_KEY!,
    base: process.env.TRIEVE_BASE!,
  },
});

MDX Plugins

Code Highlighting

import { rehypeCode } from 'fumadocs-core/mdx/rehype-code';

export const mdxOptions = {
  rehypePlugins: [rehypeCode()],
};

Admonitions (Alerts)

import { remarkAdmonition } from 'fumadocs-core/mdx/remark-admonition';

export const mdxOptions = {
  remarkPlugins: [remarkAdmonition()],
};

TypeScript/JavaScript Toggle

import { remarkTS2JS } from 'fumadocs-core/mdx/remark-ts2js';

export const mdxOptions = {
  remarkPlugins: [remarkTS2JS()],
};

Image Size

import { remarkImage } from 'fumadocs-core/mdx/remark-image';

export const mdxOptions = {
  remarkPlugins: [remarkImage()],
};

MDX Structure Extraction

import { remarkStructure } from 'fumadocs-core/mdx/remark-structure';

export const mdxOptions = {
  remarkPlugins: [remarkStructure()],
};

Page Tree Configuration

Root Folders

Create meta.json in the folder:

{
  "title": "Components",
  "description": "Component documentation",
  "root": true
}

Custom Page Tree

import type { PageTree } from 'fumadocs-core/page-tree';

const tree: PageTree.Root = {
  name: 'docs',
  children: [
    {
      name: 'getting-started',
      children: [
        {
          name: 'introduction.mdx',
          url: '/docs/getting-started/introduction',
        },
      ],
      url: '/docs/getting-started',
    },
  ],
};

Reference Documentation:

• Headless Documentation
• Components List
• Search Integration
• MDX Plugins
• Content Collections