Mintlify

Fumadocs

Fumadocs is an open-source, self-hosted documentation platform that serves as a great alternative to Mintlify. This document itself is written using Fumadocs. It is based on Next.js and uses MDX for documentation. With Fumadocs, you can easily deploy a standalone documentation site or add a /docs subdirectory to your existing website.

This article demonstrates how to add Fumadocs to the /docs subdirectory of your Next.js website.

Installation

Suppose your website is www.example.com, and you want to add a www.example.com/lee` directory.

You can easily run a Fumadocs site locally by following the Fumadocs documentation. Detailed installation steps can be found in the official Fumadocs documentation.

npm create fumadocs-app

Setting Up a Subdirectory

For example, this site publishes the documentation system to the main site through the /lee subdirectory. You can plan your desired subdirectory. Then, set the basePath in the next.config.mjs file in the Fumadocs main directory:

import { createMDX } from 'fumadocs-mdx/next';
 
const withMDX = createMDX();
 
/** @type {import('next').NextConfig} */
 
const config = {
  reactStrictMode: true,
  output: 'standalone',
  basePath: '/lee'
};
 
export default withMDX(config);

At this point, you must access the documentation system via http://127.0.0.1:3000/lee. Once deployed remotely, you can access it via https://sub.example.com/lee.

Setting Up Reverse Proxy for Your Main Site: Rewriting in Next.js

Next.js provides the rewrites configuration item, which can be used to set up a reverse proxy for smooth upgrades.

In the main site's next.config.mjs, add rewrite rules:

module.exports = {
  async rewrites() {
    return [
      {
        source: '/lee',
        destination: 'https://sub.example.com/lee',
      },
      {
        source: '/lee/:path*',
        destination: 'https://sub.example.com/lee/:path*',
      }
    ]
  },
}

This way, you can access the documentation system via https://www.example.com/lee.

export const config = {
  matcher: [
    // Match all pathnames except for
    // - … if they start with `/api`, `/_next` or `/_vercel` or `/lee`
    // - … the ones containing a dot (e.g. `favicon.ico`)
    '/((?!api|lee|_next|up|_vercel|.*\\..*).*)',
  ]
};

Deploying Next.js to a Remote Server

Besides deploying to Netlify or Vercel, you can also deploy to a remote server. By using open-source alternatives, you don't have to worry about unexpected additional costs. The cost of purchasing a server is fixed, and it offers great performance and ample storage space. You can deploy not only web services but also databases, caching services, and more.

If you've purchased a server like netcup, you can deploy Next.js to the server. We'll have a separate article discussing various deployment methods, such as:

• GitHub Actions for automatic deployment
• Kamal deployment
• Coolify deployment
• Dokku deployment

If you want to learn about other deployment methods, feel free to contact me!