A Reference Object whose target eventually refers back to it overflowed the stack. The schema is now marked while its target resolves, so a cycle resolves to the sibling keywords instead of recursing forever.
Content sources can hook into the static loader they are attached to, and dynamic sources can opt out of the loader's in-memory file cache.
configureStatic runs when a source is attached to loader(), and again whenever dynamicLoader() builds a new static loader:
export function createMySource(): DynamicSource { return { cache: 'custom', async files() { return loadFiles(); }, configureStatic({ loader, source }) { // `loader` is the created static loader // `source` is the record key when using named sources }, configure(loader, { source }) { loader.invalidate(); }, };}
cache: 'memory' (default): files() is called once until invalidate().
cache: 'custom': the source caches itself. dynamicLoader() re-runs files() on get() and rebuilds only when the file list is shallowly different (by identity).
Integrations
GraphQL cross-links are generated from the attached loader instead of a baseUrl option on staticSource(). Local, OpenAPI, and AsyncAPI dynamicSource() use cache: 'custom' and reuse generated files by identity until invalidate().
Sanity now uses cache: 'custom' when given a sanityFetch from next-sanity/live, calling invalidate() in draft mode is no longer needed.
Redesign source API
Content sources can hook into the static loader they are attached to, and dynamic sources can opt out of the loader's in-memory file cache.
configureStatic runs when a source is attached to loader(), and again whenever dynamicLoader() builds a new static loader:
export function createMySource(): DynamicSource { return { cache: 'custom', async files() { return loadFiles(); }, configureStatic({ loader, source }) { // `loader` is the created static loader // `source` is the record key when using named sources }, configure(loader, { source }) { loader.invalidate(); }, };}
cache: 'memory' (default): files() is called once until invalidate().
cache: 'custom': the source caches itself. dynamicLoader() re-runs files() on get() and rebuilds only when the file list is shallowly different (by identity).
Integrations
GraphQL cross-links are generated from the attached loader instead of a baseUrl option on staticSource(). Local, OpenAPI, and AsyncAPI dynamicSource() use cache: 'custom' and reuse generated files by identity until invalidate().
Sanity now uses cache: 'custom' when given a sanityFetch from next-sanity/live, calling invalidate() in draft mode is no longer needed.
Cache the document proxy in toStaticData
Matches fumadocs-openapi: the magic proxy is created once per document instead of once per generated page.
Sätteri 0.10
@fumadocs/satteri now requires satteri ^0.10.3, and the plugins were rewritten on its new capabilities:
Exports (frontmatter, toc, structuredData, …) are emitted by an after document hook instead of an anchor marker appended to the source, so plugins no longer see (or need to skip) the anchor node.
remark-steps, remark-admonition and remark-code-tab still detect their targets through node visitors (so documents without the construct cost nothing), but process each parent exactly once in an after hook, replacing the per-visit dedup workarounds.
remark-llms stringifies the document root from a before hook instead of subscribing to 19 node types to find it.
Markdown documents compile through Sätteri's own markdownToJs; the hand-assembled pipeline is gone. Raw HTML in .md files is still dropped, matching the previous behavior.
rehype-katex parses KaTeX output with Sätteri's htmlToHast, dropping the hast-util-from-html dependency.
No plugin reads node.position, so Sätteri now skips source-position tracking entirely (~15% faster parse).
Breaking:ExtraPluginHooks.beforeToJs was removed. Seed ctx.data from a Sätteri before hook on the plugin definition instead — it also receives the document root:
@fumadocs/satteri now requires satteri ^0.10.3, and the plugins were rewritten on its new capabilities:
Exports (frontmatter, toc, structuredData, …) are emitted by an after document hook instead of an anchor marker appended to the source, so plugins no longer see (or need to skip) the anchor node.
remark-steps, remark-admonition and remark-code-tab still detect their targets through node visitors (so documents without the construct cost nothing), but process each parent exactly once in an after hook, replacing the per-visit dedup workarounds.
remark-llms stringifies the document root from a before hook instead of subscribing to 19 node types to find it.
Markdown documents compile through Sätteri's own markdownToJs; the hand-assembled pipeline is gone. Raw HTML in .md files is still dropped, matching the previous behavior.
rehype-katex parses KaTeX output with Sätteri's htmlToHast, dropping the hast-util-from-html dependency.
No plugin reads node.position, so Sätteri now skips source-position tracking entirely (~15% faster parse).
Breaking:ExtraPluginHooks.beforeToJs was removed. Seed ctx.data from a Sätteri before hook on the plugin definition instead — it also receives the document root:
Add a main landmark to docs, notebook and flux pages
The page container slot now wraps <article id="nd-page"> in a <main class="contents"> in the docs, notebook and flux layouts. All props, id="nd-page" and the layout classes stay on the <article>, so existing selectors and refs keep working.
Loader: next parameter for custom slugs function
The slugs option now receives a next function as its second argument, which generates the default slugs from the file path. This lets custom slug functions build on the default generation instead of reimplementing it:
loader({ slugs(file, next) { if (file.path.startsWith('blog/')) return ['blog', ...next()]; // return `undefined` to generate default slugs },});
Behavior change: conflicting cases like dir/index.mdx vs dir.mdx are now resolved for custom slugs functions as well. Index files are always processed after other pages, and receive an index suffix when their slugs (custom or default) collide with an existing page — previously, custom slugs functions that produced such collisions threw a Duplicated slugs error.
New package: @fumadocs/local-html
A content source for local HTML files. It integrates externally-produced HTML pages (exported decks, reports, agent-generated deliverables) into a Fumadocs site, adapting them to the docs theme: content is scoped to <main>/<article>, page chrome and scripts/styles are dropped, class/style attributes are removed so prose styling takes over, and headings get generated ids for TOC and search indexing.
Code blocks are highlighted with Shiki, configured through rehypeCodeOptions like @fumadocs/local-md (false to skip it). The language comes from the block's language-* class, which now survives adaptStyles.
Hot reload works like @fumadocs/local-md: @fumadocs/local-html/dev/vite for Vite, or the bundled local-html dev server with @fumadocs/local-html/dev/ws for everything else.
@fumadocs/base-ui@16.14.4
fumadocs-core@16.14.4
fumadocs-ui@16.14.4
Introduce @fumari/image-size, replacing image-size in remarkImage
import { probe, imageSize } from '@fumari/image-size';await probe('./public/banner.png'); // { width: 1200, height: 630, type: 'png', mime: 'image/png' }await probe('https://example.com/banner.png', { timeout: 5000 });imageSize(bytes); // the same result, or `null`
remarkImage now uses it in both fumadocs-core and @fumadocs/satteri. Remote images are no longer downloaded in full just to be measured, and redirects are followed. Sizes are always in pixels, so an SVG sized in em or pt is converted instead of being skipped. Remote requests also time out after 30 seconds by default.
One behaviour difference worth knowing: the supported formats are avif/heic/heif, bmp, gif, ico, jpeg, png, psd, svg, tiff and webp. Sizes for jxl, tga, pnm, dds, icns, cur, ktx and jp2 can no longer be resolved and go through onError instead.
Sequential scanning stops after 512 KB, but that never loses an image: the one format that stores its dimensions past that point — TIFF with a trailing IFD — is resolved by following the header's pointer with a targeted read, using an HTTP Range request for remote files (and skipping through the body when the server ignores ranges).
Introduce @fumari/image-size, replacing image-size in remarkImage
import { probe, imageSize } from '@fumari/image-size';await probe('./public/banner.png'); // { width: 1200, height: 630, type: 'png', mime: 'image/png' }await probe('https://example.com/banner.png', { timeout: 5000 });imageSize(bytes); // the same result, or `null`
remarkImage now uses it in both fumadocs-core and @fumadocs/satteri. Remote images are no longer downloaded in full just to be measured, and redirects are followed. Sizes are always in pixels, so an SVG sized in em or pt is converted instead of being skipped. Remote requests also time out after 30 seconds by default.
One behaviour difference worth knowing: the supported formats are avif/heic/heif, bmp, gif, ico, jpeg, png, psd, svg, tiff and webp. Sizes for jxl, tga, pnm, dds, icns, cur, ktx and jp2 can no longer be resolved and go through onError instead.
Sequential scanning stops after 512 KB, but that never loses an image: the one format that stores its dimensions past that point — TIFF with a trailing IFD — is resolved by following the header's pointer with a targeted read, using an HTTP Range request for remote files (and skipping through the body when the server ignores ranges).
Introduce @fumari/image-size, replacing image-size in remarkImage
import { probe, imageSize } from '@fumari/image-size';await probe('./public/banner.png'); // { width: 1200, height: 630, type: 'png', mime: 'image/png' }await probe('https://example.com/banner.png', { timeout: 5000 });imageSize(bytes); // the same result, or `null`
remarkImage now uses it in both fumadocs-core and @fumadocs/satteri. Remote images are no longer downloaded in full just to be measured, and redirects are followed. Sizes are always in pixels, so an SVG sized in em or pt is converted instead of being skipped. Remote requests also time out after 30 seconds by default.
One behaviour difference worth knowing: the supported formats are avif/heic/heif, bmp, gif, ico, jpeg, png, psd, svg, tiff and webp. Sizes for jxl, tga, pnm, dds, icns, cur, ktx and jp2 can no longer be resolved and go through onError instead.
Sequential scanning stops after 512 KB, but that never loses an image: the one format that stores its dimensions past that point — TIFF with a trailing IFD — is resolved by following the header's pointer with a targeted read, using an HTTP Range request for remote files (and skipping through the body when the server ignores ranges).
Fix Base UI's use-sync-external-store breaking Vite dev servers
The Vite config is now derived from your project's own dependencies at startup, instead of being generated ahead of time against ours.
Builds keep the alias that replaces the shim with React, which is now applied only there. Pre-bundling is a dev server feature, and on builds a bundler that leaves the shim's require('react') in place gives it a second React instance whose hook dispatcher is null, breaking every component with a Base UI store.
@fumadocs/base-ui@16.14.2
fumadocs-core@16.14.2
fumadocs-ui@16.14.2
Fix crash in DynamicCodeBlock when options is undefined
DynamicCodeBlock read options.components unconditionally while building its Shiki config, even though options is optional on the public wrapper component. Passing an explicit options={undefined} (e.g. a value forwarded from another optional prop) crashed with Cannot read properties of undefined (reading 'components') instead of falling back to the default pre renderer.
options is now read with optional chaining, so an undefined options behaves the same as omitting the prop entirely.
@fumadocs/base-ui@16.14.1
fumadocs-core@16.14.1
fumadocs-ui@16.14.1
Fix unusable tokenizer search option
The search engine rejects a language alongside a custom tokenizer, since the tokenizer carries its own. Both search entry points supplied one unconditionally — createDB/createDBSimple through a destructuring default that language: undefined could not suppress, and createI18nSearchAPI by hardcoding multilingual after the spread — so passing tokenizer always threw NO_LANGUAGE_WITH_CUSTOM_TOKENIZER at index-build time. On i18n sources there was no call that worked at all.
language is now omitted when a tokenizer is present (from either tokenizer or components.tokenizer), and i18n servers no longer overwrite a caller-supplied language. Attaching a stemmer to the default multilingual segmentation works as documented:
The playground's Variables panel exposes every argument of an operation, but the generated query only declares the required ones. Setting an optional argument used to send a variable the document never references, which servers ignore — the request looked successful but ran without it.
The query's variable declarations now follow the panel: setting an argument declares it, unsetting removes it. Sending an operation declares whatever the panel has set, so a query edited by hand can no longer drop a value. Declarations and values written by hand are never rewritten.
Also fixes the playground's form editing the example rendered on the page, which made Reset restore edited values instead of the original ones.
Introduce @fumadocs/graphql
Generate API reference docs from your GraphQL schemas, similar to the OpenAPI/AsyncAPI integration.
It accepts SDL files (including extend type), SDL text, introspection results, and GraphQLSchema instances, and generates per-operation & per-type pages with arguments/fields, deprecations, custom directive callouts, and example queries/responses.
Highlights:
Playground: syntax-highlighted query editor with live validation, a typed variables form generated from argument types, per-endpoint header presets, and GraphQL-aware error display. Configurable via playground.url, allowUrlEdit, headers, fetcher and render.
Usage backlinks: type pages list where a type is returned, used as a field, or accepted as input.
Cross-linking out of the box: pass baseUrl (the baseUrl of your loader()) to staticSource() and type & operation references link to their pages automatically.
Request snippets: generated cURL & JavaScript tabs next to the example query.
Introduce @fumadocs/graphql
Generate API reference docs from your GraphQL schemas, similar to the OpenAPI/AsyncAPI integration.
It accepts SDL files (including extend type), SDL text, introspection results, and GraphQLSchema instances, and generates per-operation & per-type pages with arguments/fields, deprecations, custom directive callouts, and example queries/responses.
Highlights:
Playground: syntax-highlighted query editor with live validation, a typed variables form generated from argument types, per-endpoint header presets, and GraphQL-aware error display. Configurable via playground.url, allowUrlEdit, headers, fetcher and render.
Usage backlinks: type pages list where a type is returned, used as a field, or accepted as input.
Cross-linking out of the box: pass baseUrl (the baseUrl of your loader()) to staticSource() and type & operation references link to their pages automatically.
Request snippets: generated cURL & JavaScript tabs next to the example query.
@fumadocs/base-ui@16.14.0
fumadocs-core@16.14.0
fumadocs-ui@16.14.0
Replace Orama with ZBSearch, zero-config i18n search
The built-in search engine moved from @orama/orama to ZBSearch, a near drop-in successor. All module paths and APIs are unchanged, and search now works with every language out of the box: the new default multilingual mode uses Unicode word segmentation, so i18n search needs zero config.
import { createFromSource } from 'fumadocs-core/search/server';// no `localeMap`, no `@orama/tokenizers`, CJK includedexport const { GET } = createFromSource(source);
All locales now share a single search database — results are filtered by the locale of your pages at query time. Same for static mode:
oramaStaticClient → staticClient (old name kept as deprecated alias)
initOrama → initDB, it now creates a ZBSearch instance and is optional — the exported data restores the tokenizer on load
Deprecated
localeMap is no longer needed. It still works for language-specific stemming/stop-words and keeps the legacy per-locale databases when specified.
Notes for advanced usage
language, components, plugins and search options are now typed against ZBSearch instead of @orama/orama — custom tokenizers or plugins written for Orama must be swapped to their ZBSearch equivalents.
The exported static search data is now a ZBSearch database (i18n exports became a single unified database), so server and client should be on the same fumadocs-core version.
@orama/orama and @orama/tokenizers can be removed from your dependencies unless you use them directly. Orama Cloud integrations (fumadocs-core/search/orama-cloud) are unaffected.