fumadocs-core/dist/source/index.d.ts

The library for building a documentation website in Next.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.
 */
declare class FileSystem<File> {
    files: Map<string, File>;
    folders: Map<string, string[]>;
    constructor(inherit?: FileSystem<File>);
    read(path: string): File | undefined;
    /**
     * get the direct children of folder (in virtual file path)
     */
    readDir(path: string): string[] | undefined;
    write(path: string, file: File): void;
    delete(path: string): boolean;
    deleteDir(path: string): boolean;
    getFiles(): string[];
    makeDir(path: string): void;
}

interface LoadOptions {
    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> {
    path: string;
    absolutePath: string;
    format: 'meta';
    data: Data;
}
interface PageFile<Data extends PageData = PageData> {
    path: string;
    absolutePath: string;
    format: 'page';
    slugs: string[];
    data: Data;
}
type Transformer = (context: {
    storage: ContentStorage;
}) => void;
/**
 * @returns a map of locale and its content storage.
 *
 * in the storage, locale codes are removed from file paths, hence the same file will have same file paths in every storage.
 */
declare function loadFiles(files: VirtualFile[], options: LoadOptions, i18n: I18nConfig): Record<string, ContentStorage>;

type LoaderPlugins<Page extends PageData, Meta extends MetaData> = LoaderPlugin<Page, Meta>[];
interface LoaderPlugin<Page extends PageData = PageData, Meta extends MetaData = MetaData> {
    /**
     * transform the storage after loading
     */
    transformStorage?: (context: {
        storage: ContentStorage<Page, Meta>;
    }) => void;
    /**
     * transform the generated page tree
     */
    transformPageTree?: PageTreeTransformer<Page, Meta>;
}
declare function buildPlugins<Page extends PageData, Meta extends MetaData>(plugins: LoaderPlugins<Page, Meta>): LoaderPlugin<Page, Meta>[];

interface LegacyLoaderOptions {
    /**
     * We recommend you to use `plugins` instead
     */
    transformers?: Transformer[];
}
interface LegacyPageTreeOptions<Page extends PageData, Meta extends MetaData> {
    /**
     * @deprecated use `plugins` instead
     */
    attachFile?: (node: Item, file?: PageFile<Page>) => Item;
    /**
     * @deprecated use `plugins` instead
     */
    attachFolder?: (node: Folder, folder: {
        children: (PageFile<Page> | MetaFile<Meta>)[];
    }, meta?: MetaFile<Meta>) => Folder;
    /**
     * @deprecated use `plugins` instead
     */
    attachSeparator?: (node: Separator) => Separator;
    /**
     * We recommend you to use `plugins` instead
     */
    transformers?: PageTreeTransformer<Page, Meta>[];
}

type IconResolver = (icon: string | undefined) => ReactNode;

interface LoaderConfig {
    source: SourceConfig;
    i18n: I18nConfig | undefined;
}
interface SourceConfig {
    pageData: PageData;
    metaData: MetaData;
}
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?: IconResolver;
    slugs?: (info: FileInfo) => string[];
    url?: UrlFn;
    /**
     * Additional options for page tree builder
     */
    pageTree?: Partial<BaseOptions> & LegacyPageTreeOptions<Config['pageData'], Config['metaData']>;
    plugins?: LoaderPlugins<Config['pageData'], Config['metaData']>;
}
interface Source<Config extends SourceConfig> {
    /**
     * @internal
     */
    _config?: Config;
    files: VirtualFile[] | (() => VirtualFile[]);
}
interface SharedFileInfo {
    /**
     * Virtualized file path (parsed)
     *
     * @deprecated Use `path` instead.
     */
    file: FileInfo;
    /**
     * Virtualized file path (relative to content directory)
     *
     * @example `docs/page.mdx`
     */
    path: string;
    /**
     * Absolute path of the file
     */
    absolutePath: string;
}
interface VirtualFile {
    /**
     * Virtualized path (relative to content directory)
     *
     * @example `docs/page.mdx`
     */
    path: string;
    /**
     * Absolute path of the file
     */
    absolutePath?: string;
    type: 'page' | 'meta';
    /**
     * Specified Slugs for page
     */
    slugs?: string[];
    data: unknown;
}
interface Page<Data = PageData> extends SharedFileInfo {
    slugs: string[];
    url: string;
    data: Data;
    locale?: string | undefined;
}
interface Meta<Data = MetaData> extends SharedFileInfo {
    data: Data;
}
interface LanguageEntry<Data = PageData> {
    language: string;
    pages: Page<Data>[];
}
interface LoaderOutput<Config extends LoaderConfig> {
    pageTree: Config['i18n'] extends I18nConfig ? Record<string, Root> : Root;
    getPageTree: (locale?: string) => Root;
    getPageByHref: (href: string, options?: {
        language?: string;
        /**
         * resolve relative file paths in `href` from specified dirname, must be a virtual path.
         */
        dir?: string;
    }) => {
        page: Page<Config['source']['pageData']>;
        hash?: string;
    } | undefined;
    /**
     * @internal
     */
    _i18n?: I18nConfig;
    /**
     * Get a list of pages from specified language
     *
     * @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
     *
     * @param language - If empty, the default language will be used
     */
    getPage: (slugs: string[] | undefined, language?: string) => Page<Config['source']['pageData']> | undefined;
    getNodePage: (node: Item, language?: string) => Page<Config['source']['pageData']> | undefined;
    getNodeMeta: (node: Folder, language?: string) => Meta<Config['source']['metaData']> | undefined;
    /**
     * generate static params for Next.js SSG
     *
     * @param slug - customise parameter name for slugs
     * @param lang - customise parameter name for lang
     */
    generateParams: <TSlug extends string = 'slug', TLang extends string = 'lang'>(slug?: TSlug, lang?: TLang) => (Record<TSlug, string[]> & Record<TLang, string>)[];
}
declare function createGetUrl(baseUrl: string, i18n?: I18nConfig): UrlFn;
declare function loader<Config extends SourceConfig, I18n extends I18nConfig | undefined = undefined>(options: LoaderOptions<Config, I18n>): LoaderOutput<{
    source: Config;
    i18n: I18n;
}>;
/**
 * Convert file path into slugs, also encode non-ASCII characters, so they can work in pathname
 */
declare function getSlugs(file: string | FileInfo): string[];

interface MetaData {
    icon?: string | undefined;
    title?: string | undefined;
    root?: boolean | undefined;
    pages?: string[] | undefined;
    defaultOpen?: boolean | undefined;
    description?: string | undefined;
}
interface PageData {
    icon?: string | undefined;
    title?: string;
    description?: string | undefined;
}
type InferPageType<Utils extends LoaderOutput<any>> = Utils extends LoaderOutput<infer Config> ? Page<Config['source']['pageData']> : never;
type InferMetaType<Utils extends LoaderOutput<any>> = Utils extends LoaderOutput<infer Config> ? Meta<Config['source']['metaData']> : never;
/**
 * @internal
 */
type UrlFn = (slugs: string[], locale?: string) => string;

interface PageTreeBuilderContext<Page extends PageData = PageData, Meta extends MetaData = MetaData> {
    /**
     * @internal resolve paths without extensions
     */
    resolveName: (name: string, format: 'meta' | 'page') => string;
    options: BaseOptions;
    transformers: PageTreeTransformer<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 = 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 {
    id?: string;
    /**
     * Remove references to the file path of original nodes (`$ref`)
     *
     * @defaultValue false
     */
    noRef?: boolean;
    plugins?: LoaderPlugin[];
    /**
     * generate fallback page tree
     *
     * @defaultValue true
     */
    generateFallback?: boolean;
}
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 & {
        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 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 };