N-Docs LogoN-Docs
Fumadocs

Fumadocs Setup Guide

Simple guide to setting up and deploying Fumadocs documentation sites

Fumadocs Setup Guide

Learn how to create a professional documentation site using Fumadocs with sidebar tabs, themes, and deployment options.

Prerequisites

  • Node.js 18+ installed
  • Basic knowledge of React and Next.js
  • Code editor (VS Code recommended)

Quick Start

1. Create New Project

npx create-fumadocs-app my-docs
cd my-docs
npm install
npm run dev
pnpm create fumadocs-app my-docs
cd my-docs
pnpm install
pnpm dev
yarn create fumadocs-app my-docs
cd my-docs
yarn install
yarn dev

2. Setup Options

During setup, choose:

  • Content source: Content Collections
  • TypeScript: Yes
  • Styling: Tailwind CSS

Your site will be available at http://localhost:3000

Folder Structure

Create your documentation structure:

mkdir -p content/docs/documentation
mkdir -p content/docs/software  
mkdir -p content/docs/scripts

Basic structure:

content/docs/
├── index.mdx
├── meta.json
├── documentation/
│   ├── index.mdx
│   ├── meta.json
│   └── docker/
├── software/
│   ├── index.mdx
│   ├── meta.json
│   └── nextcloud/
└── scripts/
    ├── index.mdx
    └── meta.json

Configuration

Root Configuration

content/docs/meta.json:

{
  "title": "My Docs",
  "pages": [
    "index",
    "documentation",
    "software", 
    "scripts"
  ]
}

For sidebar tabs, add "root": true to section meta.json files:

content/docs/documentation/meta.json:

{
  "title": "Documentation",
  "root": true,
  "pages": [
    "index",
    "docker"
  ]
}

content/docs/software/meta.json:

{
  "title": "Software",
  "root": true,
  "pages": [
    "index",
    "nextcloud"
  ]
}

Adding Icons & Favicon

Modern Icons with Lucide React

Install modern icons:

pnpm add lucide-react

Update src/app/docs/layout.tsx:

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { BookOpen, Monitor, Terminal } from 'lucide-react';

export default function Layout({ children }) {
  return (
    <DocsLayout 
      tree={source.pageTree}
      sidebar={{
        tabs: {
          transform: (option) => {
            if (option.title === 'Documentation') {
              return { ...option, icon: <BookOpen className="w-4 h-4" /> };
            }
            if (option.title === 'Software') {
              return { ...option, icon: <Monitor className="w-4 h-4" /> };
            }
            if (option.title === 'Scripts') {
              return { ...option, icon: <Terminal className="w-4 h-4" /> };
            }
            return option;
          },
        },
      }}
    >
      {children}
    </DocsLayout>
  );
}

Custom Favicon

Replace default favicon by adding to src/app/layout.tsx:

import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'My Docs',
  description: 'Documentation site',
  icons: {
    icon: '/favicon.ico',
    shortcut: '/favicon-16x16.png',
    apple: '/apple-touch-icon.png',
  },
};

Add favicon files to public/ folder:

  • favicon.ico (32x32)
  • favicon-16x16.png
  • apple-touch-icon.png (180x180)

## Themes

Change theme in `src/app/global.css`:

```css
@import 'tailwindcss';
@import 'fumadocs-ui/css/vitepress.css';
@import 'fumadocs-ui/css/preset.css';

Available themes:

  • vitepress.css - Clean, minimal
  • neutral.css - Professional gray
  • dusk.css - Warm colors
  • ocean.css - Blue tones

Writing Content

Create MDX files with frontmatter:

---
title: My Page
description: Page description
---

# My Page

Content goes here.

## Using Components

<Callout type="info">
This is an info callout.
</Callout>

<Tabs items={['Tab 1', 'Tab 2']}>
<Tab value="Tab 1">
Content for tab 1
</Tab>
<Tab value="Tab 2">
Content for tab 2
</Tab>
</Tabs>

Deployment

  1. Push code to GitHub
  2. Visit vercel.com
  3. Import your repository
  4. Deploy automatically

Build for Production

npm run build

Static Export

For static hosting, update next.config.mjs:

const config = {
  output: 'export',
  trailingSlash: true,
  images: { unoptimized: true },
};

export default config;

Troubleshooting

Common issues:

Sidebar tabs not showing:

  • Add "root": true to section meta.json files
  • Don't add "root": true to the main meta.json

Build errors:

  • Check MDX syntax
  • Verify all imports exist
  • Ensure frontmatter is valid

Theme not applying:

  • Check CSS import order
  • Clear browser cache

Resources

This guide covers the basics of setting up Fumadocs. Start simple and add features as needed!

Software

Software documentation and configuration guides

Fumadocs CLI

Using the Fumadocs CLI for enhanced documentation management and components