Overview
The Source API provides interfaces and utilities for creating content sources that power your documentation. Sources represent collections of pages and metadata files that can be transformed into a page tree.
Core Types
Source
The main source interface.
interface Source<Config extends SourceConfig = SourceConfig> {
files: VirtualFile<Config>[];
}
Array of virtual files (pages and meta files) in the source
SourceConfig
Configuration for defining page and meta data types.
interface SourceConfig {
pageData: PageData;
metaData: MetaData;
}
Type definition for page data properties
Type definition for meta file data properties
PageData
Data structure for individual pages.
interface PageData {
icon?: string | undefined;
title?: string;
description?: string | undefined;
}
Icon identifier for the page
interface MetaData {
icon?: string | undefined;
title?: string | undefined;
root?: boolean | undefined;
pages?: string[] | undefined;
defaultOpen?: boolean | undefined;
collapsible?: boolean | undefined;
description?: string | undefined;
}
Mark folder as a root folder in the page tree
Explicit order of pages in the folder
Whether the folder should be open by default
Whether the folder can be collapsed
VirtualFile
Represents a file in the virtual file system.
type VirtualFile<Config extends SourceConfig = SourceConfig> =
| VirtualPage<Config['pageData']>
| VirtualMeta<Config['metaData']>;
interface VirtualPage<Data extends PageData> {
type: 'page';
path: string;
absolutePath?: string;
slugs?: string[];
data: Data;
}
interface VirtualMeta<Data extends MetaData> {
type: 'meta';
path: string;
absolutePath?: string;
data: Data;
}
Virtualized path relative to content directory (e.g., docs/page.mdx)
Absolute file system path
URL slugs for the page (pages only)
Associated data for the file
Functions
source()
Create a new source from pages and meta files.
function source<Page extends PageData, Meta extends MetaData>(config: {
pages: VirtualPage<Page>[];
metas: VirtualMeta<Meta>[];
}): Source<{
pageData: Page;
metaData: Meta;
}>;
Array of virtual page files
Array of virtual meta files
A source object containing all files
import { source } from 'fumadocs-core/source';
const mySource = source({
pages: [
{
type: 'page',
path: 'docs/getting-started.mdx',
data: {
title: 'Getting Started',
description: 'Learn the basics'
}
}
],
metas: [
{
type: 'meta',
path: 'docs/meta.json',
data: {
title: 'Documentation',
defaultOpen: true
}
}
]
});
multiple()
Combine multiple sources with type discrimination.
function multiple<T extends Record<string, Source>>(
sources: T
): Source<_ConfigUnion_<T>>;
sources
Record<string, Source>
required
Object mapping source names to Source objects
Combined source with type discrimination added to each file’s data
import { multiple } from 'fumadocs-core/source';
import { docsSource, blogSource } from './sources';
const combinedSource = multiple({
docs: docsSource,
blog: blogSource
});
// Each file now has a `type` property: 'docs' or 'blog'
update()
Update a source object with chainable transformations.
function update<Config extends SourceConfig>(
source: Source<Config>
): _SourceUpdate_<Config>;
interface _SourceUpdate_<Config extends SourceConfig> {
files<Page extends PageData, Meta extends MetaData>(
fn: (files: VirtualFile<Config>[]) => (VirtualPage<Page> | VirtualMeta<Meta>)[]
): _SourceUpdate_<{pageData: Page; metaData: Meta}>;
page<V extends PageData>(
fn: (page: VirtualPage<Config['pageData']>) => VirtualPage<V>
): _SourceUpdate_<{pageData: V; metaData: Config['metaData']}>;
meta<V extends MetaData>(
fn: (meta: VirtualMeta<Config['metaData']>) => VirtualMeta<V>
): _SourceUpdate_<{pageData: Config['pageData']; metaData: V}>;
build(): Source<Config>;
}
Chainable update builder with methods:
files(fn): Transform all filespage(fn): Transform only page filesmeta(fn): Transform only meta filesbuild(): Return the updated source
import { update } from 'fumadocs-core/source';
const updatedSource = update(mySource)
.page(page => ({
...page,
data: {
...page.data,
lastModified: new Date().toISOString()
}
}))
.meta(meta => ({
...meta,
data: {
...meta.data,
collapsible: true
}
}))
.build();
Storage Adapters
FileSystem
In-memory file system for managing virtual files.
class FileSystem<File> {
files: Map<string, File>;
folders: Map<string, string[]>;
constructor(inherit?: FileSystem<File>);
read(path: string): File | undefined;
readDir(path: string): string[] | undefined;
write(path: string, file: File): void;
delete(path: string, recursive?: boolean): boolean;
getFiles(): string[];
makeDir(path: string): void;
}
read(path)
(path: string) => File | undefined
Read a file at the specified path
readDir(path)
(path: string) => string[] | undefined
Get direct children of a folder
write(path, file)
(path: string, file: File) => void
Write a file to the file system
delete(path, recursive?)
(path: string, recursive?: boolean) => boolean
Delete a file or directory. Set recursive to true to delete directories with contents.
Get all file paths in the file system
Create a directory and all parent directories
import { FileSystem } from 'fumadocs-core/source';
const fs = new FileSystem();
fs.write('docs/intro.mdx', {
content: '# Introduction',
frontmatter: { title: 'Intro' }
});
const file = fs.read('docs/intro.mdx');
const children = fs.readDir('docs');
Utilities
PathUtils
Path manipulation utilities for virtual file paths.
import * as PathUtils from 'fumadocs-core/source';
PathUtils.joinPath(...paths: string[]): string;
PathUtils.dirname(path: string): string;
PathUtils.basename(path: string, ext?: string): string;
PathUtils.extname(path: string): string;
PathUtils.splitPath(path: string): string[];
import * as PathUtils from 'fumadocs-core/source';
PathUtils.joinPath('docs', 'getting-started.mdx');
// => 'docs/getting-started.mdx'
PathUtils.dirname('docs/getting-started.mdx');
// => 'docs'
PathUtils.basename('docs/getting-started.mdx', '.mdx');
// => 'getting-started'
getSlugs()
Generate URL slugs from file paths.
function getSlugs(file: string): string[];
Array of URL slugs, with non-ASCII characters encoded
import { getSlugs } from 'fumadocs-core/source';
getSlugs('docs/getting-started.mdx');
// => ['docs', 'getting-started']
getSlugs('docs/index.mdx');
// => ['docs']
getSlugs('docs/(group)/page.mdx');
// => ['docs', 'page'] (group folders are ignored)