Mintlify

Overview

@fumapress/mintlify reads your existing Mintlify docs.json file and configures Fumapress from it.

Installation

npm i @fumapress/mintlify

Add the plugin to your config, with docs.json located in your project root:

import { defineConfig } from "fumapress";
import { docs } from "./.source/server";
import { mintlifyPlugin } from "@fumapress/mintlify";

export default defineConfig({
  content: {
    docs: docs.toFumadocsSource(),
  },
})
  .plugins(mintlifyPlugin());

Your MDX pages should live in the content/docs folder (paths in docs.json are resolved against it, a docs/ or content/docs/ prefix in navigation entries is ignored).

Options

mintlifyPlugin({
  // path to docs.json, relative to project root
  path: "docs.json",
  // docs collection folder name inside `content/`
  docsDir: "docs",
  // disable individual features to take manual control
  features: {
    navigation: true,
    navbar: true,
    theme: true,
    appearance: true,
    banner: true,
    footer: true,
    redirects: true,
    notFound: true,
    search: true,
    metadata: true,
  },
});

Internationalization

When docs.json defines navigation.languages, configure i18n with defineMintlifyI18n():

import { defineConfig } from "fumapress";
import { defineMintlifyI18n, mintlifyPlugin, readMintlifyDocs } from "@fumapress/mintlify";

const mintlifyDocs = readMintlifyDocs();

export default defineConfig({
  content: {
    // ...
  },
  translations: defineMintlifyI18n(mintlifyDocs, {
    // optionally map Mintlify locales to your own locale codes
    localeMap: { cn: "zh" },
  }).translations(),
}).plugins(mintlifyPlugin());

OpenAPI & AsyncAPI

api.openapi sources (file paths or URLs) can be forwarded to Fumadocs OpenAPI:

import { defineConfig } from "fumapress";
import { docs } from "./.source/server";
import { mintlifyPlugin } from "@fumapress/mintlify";
import { createMintlifyOpenAPI } from "@fumapress/mintlify/openapi";
import { openapiPlugin } from "fumapress/plugins/openapi";

const openapi = createMintlifyOpenAPI();

export default defineConfig({
  content: {
    docs: docs.toFumadocsSource(),
    openapi: await openapi.staticSource(),
  },
}).plugins(mintlifyPlugin(), openapiPlugin({ server: openapi }));

api.asyncapi sources work the same way with createMintlifyAsyncAPI from @fumapress/mintlify/asyncapi and the AsyncAPI plugin.

api.playground.proxy is respected (proxy enabled by default at /api/proxy). Other api options are not supported, see the support matrix.

Support Matrix

All valid docs.json files parse successfully — unsupported properties are accepted and ignored, so migration never breaks on them.

This page covers docs.json only. MDX content (Mintlify components like <Card>, <Accordion>, frontmatter conventions) is handled by your content adapter, not by this plugin.

Supported

Partially supported

Not supported

Notes

• Icons: navigation, navbar and group icons resolve to Lucide components on the server, no extra client JavaScript is shipped.
• Banner & footer are rendered outside the docs layout so they appear on every page.
• $ref resolution: docs.json may reference other JSON files with $ref, they are resolved (and validated to stay inside your project root) before parsing.