Nexus Docs CLI

A powerful CLI tool that transforms any project's /docs folder into a beautiful, searchable documentation site using Fumadocs. Works in ANY repository - just add a /docs folder with MDX files, run the CLI, and you're ready to serve or deploy.

🎯 Overview

Nexus Docs CLI makes documentation dead simple:

1. Add /docs folder to your project with MDX files
2. Run nexus-docs init - CLI detects your docs and sets up Fumadocs
3. Serve locally with nexus-docs serve
4. Deploy to Vercel with nexus-docs deploy

The CLI automatically creates a .fumadocs/ configuration folder that handles all the Fumadocs magic, while your actual content stays in /docs.

Why This Approach?

• 🚀 Zero Config: Just add /docs folder, CLI handles everything
• 📁 Clean Separation: Documentation lives in /docs, Fumadocs config in .fumadocs/
• 🔄 Universal: Works in any project (React, Vue, Node.js, Python, etc.)
• 🎨 Fumadocs Powered: Full power of Fumadocs UI, search, and features
• ☁️ One-Click Deploy: Deploy to Vercel with a single command

📚 What is Fumadocs?

Fumadocs is a modern documentation framework that provides:

• Beautiful UI: Pre-built, customizable components
• Smart Search: Built-in Orama/Algolia search
• MDX Support: Write docs with React components
• Auto Navigation: Generates sidebar from file structure
• Table of Contents: Auto-generated TOC with active highlighting
• Dark Mode: Built-in theme switching
• i18n Support: Multi-language documentation
• Type-Safe: TypeScript-first approach

🚀 Quick Start

Installation

npm install -g nexus-docs-cli

In Your Project

# 1. Navigate to your project
cd my-awesome-project

# 2. Create docs folder with your first MDX file
mkdir docs
cat > docs/index.mdx << 'EOF'
---
title: Welcome
description: Documentation for My Awesome Project
---

# Welcome

This is the documentation for My Awesome Project.

## Getting Started

Follow these steps to get started...
EOF

# 3. Initialize Nexus Docs (creates .fumadocs/ folder)
nexus-docs init

# 4. Serve locally
nexus-docs serve

# 5. Deploy to Vercel
nexus-docs deploy

That's it! Your documentation is now available.

🏗️ How It Works

Project Structure

my-awesome-project/
├── .nexusdocs/             # ← Created by CLI (gitignored)
│   ├── app/               # Next.js app with Fumadocs
│   ├── source.config.ts   # Points to ../docs
│   ├── next.config.mjs
│   ├── .env.local         # Auto-copied from docs/.env.local
│   └── package.json
│
├── docs/                   # ← Your documentation (committed to git)
│   ├── nexus-docs.config.json  # ← Project configuration
│   ├── .env.example       # ← Environment variables template
│   ├── .env.local         # ← Your secrets (gitignored)
│   ├── index.mdx          # Homepage
│   ├── getting-started/
│   │   ├── index.mdx
│   │   └── installation.mdx
│   ├── api/
│   │   ├── authentication.mdx
│   │   └── endpoints.mdx
│   └── meta.json          # Optional: customize sidebar
│
├── src/                    # Your project code
├── package.json
└── .gitignore             # Add .nexusdocs/ to gitignore

Important Changes (v0.2.0):

• Folder renamed from .fumadocs/ to .nexusdocs/
• Configuration moved: nexus-docs.config.json now in /docs folder
• Environment files: .env.example and .env.local now in /docs folder
• Auto-copy: .env.local automatically copied from /docs to .nexusdocs when running serve/build

The .nexusdocs/ Folder

The CLI automatically creates and manages this folder:

• Purpose: Contains Fumadocs/Next.js configuration
• Location: Root of your project
• Git: Should be in .gitignore (generated, not committed)
• Content:
  • Next.js app that serves your /docs
  • Fumadocs configuration
  • Build artifacts
  • Auto-copied .env.local from /docs folder

Note: As of v0.2.0, this folder has been renamed from .fumadocs/ to .nexusdocs/ for better project clarity.

The /docs Folder

This is where YOUR documentation lives:

• Purpose: Your actual MDX documentation files
• Location: Root of your project
• Git: Committed to version control
• Standard: Follows Fumadocs file structure conventions

📖 Documentation Standards

File Structure

docs/
├── index.mdx              # Required: Documentation homepage
├── getting-started/       # Folders create sections
│   ├── index.mdx         # Section homepage
│   ├── installation.mdx
│   └── configuration.mdx
├── guides/
│   ├── basics.mdx
│   └── advanced.mdx
├── api/
│   ├── reference.mdx
│   └── examples.mdx
└── meta.json             # Optional: customize navigation

MDX File Format

Every MDX file should have frontmatter:

---
title: Page Title
description: Page description for SEO
icon: 🚀                    # Optional: icon for sidebar
---

# Page Title

Your content here...

## Section

You can use all Fumadocs components:

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

<Tabs items={['npm', 'pnpm', 'yarn']}>
  <Tab value="npm">
    ```bash
    npm install package
    ```
  </Tab>
</Tabs>

Navigation (meta.json)

Customize sidebar order and grouping:

{
  "title": "Getting Started",
  "pages": [
    "installation",
    "configuration",
    "first-steps"
  ]
}

🔧 CLI Commands

init

Initialize Fumadocs in your project.

nexus-docs init

# Options
nexus-docs init --port 3001    # Custom port
nexus-docs init --no-install   # Skip dependency installation

What it does:

1. Detects /docs folder
2. Creates .nexusdocs/ configuration
3. Generates Fumadocs setup pointing to your /docs
4. Creates docs/nexus-docs.config.json with project settings
5. Creates docs/.env.example template
6. Adds .nexusdocs/ to .gitignore
7. Installs dependencies

serve

Start local development server.

nexus-docs serve

# Options
nexus-docs serve --port 3001   # Custom port
nexus-docs serve --open        # Open browser
nexus-docs serve --turbo       # Use Turbopack

Runs on: http://localhost:3000 (or custom port)

What it does:

1. Checks for .nexusdocs/ folder
2. Auto-copies docs/.env.local to .nexusdocs/.env.local (if exists)
3. Installs dependencies if needed
4. Starts Next.js development server with hot reload

deploy

Deploy to Vercel via GitHub (Recommended).

Step-by-Step Deployment

1. Push Your Project to GitHub

Make sure .fumadocs/ is in .gitignore (automatically added by nexus-docs init):

git add .
git commit -m "Add documentation"
git push

2. Import to Vercel

1. Go to vercel.com and sign in
2. Click "Add New..." → "Project"
3. Import your GitHub repository
4. Configure Project:
   • Framework Preset: Next.js
   • Root Directory: .fumadocs ← CRITICAL!
   • Build Command: npm run build (default)
   • Output Directory: .next (default)

3. Add Environment Variables

In Vercel project settings → Environment Variables, add:

AZURE_AD_CLIENT_ID=your-client-id
AZURE_AD_CLIENT_SECRET=your-client-secret
AZURE_AD_TENANT_ID=your-tenant-id
NEXTAUTH_URL=https://your-project.vercel.app
NEXTAUTH_SECRET=your-generated-secret

Important Notes:

• NEXTAUTH_URL must be your actual production URL
• Generate NEXTAUTH_SECRET with: openssl rand -base64 32
• Update Azure AD redirect URI to: https://your-project.vercel.app/api/auth/callback/azure-ad

4. Deploy

Click Deploy and wait for build to complete.

CLI Deployment (Alternative)

# Install Vercel CLI
npm install -g vercel

# Deploy from project root
nexus-docs deploy

# Options
nexus-docs deploy --prod                    # Deploy to production
nexus-docs deploy --token YOUR_TOKEN        # Vercel token
nexus-docs deploy --project my-docs         # Custom project name

Note: Environment variables must be set via Vercel dashboard first.

build

Build documentation for production.

nexus-docs build

# Outputs to .fumadocs/.next/

clean

Clean generated files.

nexus-docs clean

# Removes .fumadocs/ folder

🎨 Fumadocs Features

Built-in Components

Use these in your MDX files:

Callouts

<Callout type="info">
  Important information
</Callout>

<Callout type="warn">
  Warning message
</Callout>

<Callout type="error">
  Error message
</Callout>

Tabs

<Tabs items={['npm', 'pnpm', 'yarn']}>
  <Tab value="npm">
    ```bash
    npm install
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm add
    ```
  </Tab>
</Tabs>

Steps

<Steps>
  <Step>
    ### First Step
    Do this first
  </Step>
  
  <Step>
    ### Second Step
    Then do this
  </Step>
</Steps>

Cards

<Cards>
  <Card title="Guide" href="/docs/guide">
    Learn the basics
  </Card>
  <Card title="API" href="/docs/api">
    API reference
  </Card>
</Cards>

File Tree

<Files>
  <Folder name="src">
    <File name="index.ts" />
    <File name="utils.ts" />
  </Folder>
</Files>

Search

Search is automatically enabled! Just start typing in the search bar.

Dark Mode

Toggle between light/dark themes with the built-in theme switcher.

Table of Contents

Automatically generated from your headings (##, ###).

🔌 Advanced Features

Internationalization

Support multiple languages:

# Enable i18n
nexus-docs i18n setup --locales en,tr,de

# Structure
docs/
├── en/
│   ├── index.mdx
│   └── guide.mdx
├── tr/
│   ├── index.mdx
│   └── rehber.mdx
└── de/
    └── ...

Custom Components

Add custom React components to your docs:

# Create components folder
mkdir docs/components

# Add component
cat > docs/components/CustomButton.tsx << 'EOF'
export function CustomButton({ children }) {
  return <button className="custom-btn">{children}</button>;
}
EOF

# Use in MDX
<CustomButton>Click me</CustomButton>

Custom Styling

Customize theme colors:

# Creates .fumadocs/tailwind.config.ts
nexus-docs theme customize \
  --primary "#FF6B35" \
  --secondary "#004E89"

Analytics

Add analytics to track documentation usage:

# Adds Vercel Analytics
nexus-docs analytics enable

🌍 Real-World Examples

Example 1: Open Source Project

my-cli-tool/
├── .fumadocs/           # Generated
├── docs/
│   ├── index.mdx       # "Welcome to My CLI Tool"
│   ├── installation.mdx
│   ├── usage/
│   │   ├── basic.mdx
│   │   └── advanced.mdx
│   └── api/
│       └── reference.mdx
├── src/                # Your CLI code
└── package.json

nexus-docs init
nexus-docs serve --open
nexus-docs deploy --prod

Example 2: API Documentation

my-api/
├── docs/
│   ├── index.mdx
│   ├── authentication.mdx
│   ├── endpoints/
│   │   ├── users.mdx
│   │   ├── posts.mdx
│   │   └── comments.mdx
│   └── examples/
│       └── curl.mdx
└── server/             # Your API code

Example 3: Component Library

ui-library/
├── docs/
│   ├── index.mdx
│   ├── components/
│   │   ├── button.mdx
│   │   ├── input.mdx
│   │   └── modal.mdx
│   └── guides/
│       ├── theming.mdx
│       └── customization.mdx
└── packages/           # Your components

🚦 Workflow Examples

Development Workflow

# 1. Edit docs
vim docs/new-feature.mdx

# 2. Preview changes
nexus-docs serve --open

# 3. Commit changes
git add docs/new-feature.mdx
git commit -m "Add new feature docs"

# 4. Deploy
nexus-docs deploy

Team Workflow

# Developer 1: Adds feature
git checkout -b feature/new-api
# ... code changes ...
mkdir -p docs/api
echo "# New API" > docs/api/new-endpoint.mdx
git commit -am "Add new API endpoint with docs"
git push

# Developer 2: Reviews PR
git checkout feature/new-api
nexus-docs serve --port 3001
# Review docs at localhost:3001

# After merge
git checkout main
git pull
nexus-docs deploy --prod

CI/CD Workflow

# .github/workflows/docs.yml
name: Deploy Docs

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install CLI
        run: npm install -g nexus-docs-cli
        
      - name: Deploy
        run: nexus-docs deploy --prod --token ${{ secrets.VERCEL_TOKEN }}

🔍 Configuration

Global Config

Located at ~/.nexus-docs-cli/config.json:

{
  "defaultPort": 3000,
  "autoOpen": true,
  "vercel": {
    "token": "your-token"
  }
}

Project Config

The CLI creates .fumadocs/nexus-docs.json:

{
  "docsDir": "docs",
  "port": 3000,
  "fumadocs": {
    "features": {
      "search": true,
      "darkMode": true,
      "toc": true
    }
  }
}

🐛 Troubleshooting

Docs folder not detected

# Make sure you have a docs/ folder
ls docs/

# Must contain at least one MDX file
ls docs/*.mdx

Port already in use

# Use different port
nexus-docs serve --port 3001

# Or kill process on port 3000
lsof -ti:3000 | xargs kill -9

Build errors

# Clean and rebuild
nexus-docs clean
nexus-docs init
nexus-docs serve

Deployment fails

# Check Vercel token
echo $VERCEL_TOKEN

# Build locally first
nexus-docs build

# Try deploying again
nexus-docs deploy --prod

🔍 Configuration

Project Configuration (nexus-docs.config.json)

Customize your documentation site by creating/editing docs/nexus-docs.config.json:

{
  "name": "My Project",
  "description": "Project documentation",
  "logo": "/logo.png",
  "links": {
    "github": "https://github.com/username/repo",
    "discord": "https://discord.gg/invite",
    "twitter": "https://twitter.com/username"
  }
}

Location: This file is now located in the /docs folder (as of v0.2.0), not in the project root. This keeps all documentation-related configuration together with your docs.

Configuration Options

• name (string): Project name shown in navbar
• description (string): Project description for SEO
• logo (string): Path to logo image (e.g., /logo.png)
• links (object): Social/repository links
  • github: GitHub repository URL
  • discord: Discord invite link
  • twitter: Twitter profile URL

The config file is automatically created when you run nexus-docs init with defaults from your package.json.

Authentication Configuration

Nexus Docs CLI includes built-in Azure AD authentication. All documentation pages are protected by default.

After running nexus-docs init, you'll find .env.example in your /docs folder. Copy it to .env.local in the same folder:

cp docs/.env.example docs/.env.local

Then fill in your Azure AD credentials:

# docs/.env.local (NOT in project root or .nexusdocs/)

# Azure AD Configuration
AZURE_AD_CLIENT_ID=your-client-id-here
AZURE_AD_CLIENT_SECRET=your-client-secret-here
AZURE_AD_TENANT_ID=your-tenant-id-here

# NextAuth Configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-here-generate-with-openssl-rand-base64-32

Important (v0.2.0 Update):

• Environment files are now located in the /docs folder alongside your documentation
• The CLI automatically copies docs/.env.local to .nexusdocs/.env.local when running serve or build
• Keep your secrets in docs/.env.local (gitignored) and commit docs/.env.example as a template
• No need to manually manage .env.local in .nexusdocs/ - it's auto-synced!

Generate NEXTAUTH_SECRET:

openssl rand -base64 32

Azure AD Setup

1. Go to Azure Portal
2. Navigate to Azure Active Directory > App registrations
3. Click New registration
4. Set redirect URIs:
   • Development: http://localhost:3000/api/auth/callback/azure-ad
   • Production: https://your-project.vercel.app/api/auth/callback/azure-ad
5. Copy Application (client) ID → AZURE_AD_CLIENT_ID
6. Copy Directory (tenant) ID → AZURE_AD_TENANT_ID
7. Go to Certificates & secrets > New client secret
8. Copy the secret value → AZURE_AD_CLIENT_SECRET

Important for Production:

• Add production redirect URI in Azure AD after deploying
• Update NEXTAUTH_URL in Vercel environment variables
• Redeploy after adding environment variables

Authentication Behavior

• All documentation pages require Microsoft account authentication
• Users are automatically redirected to Azure AD login
• After successful login, users can access all documentation
• Static assets (images, logos) remain publicly accessible

Custom Logo

To use a custom logo:

1. Add your logo file to .fumadocs/public/ (e.g., logo.png)
2. Update nexus-docs.config.json:

{
  "logo": "/logo.png"
}

The default logo is the Nexus logo (black diagonal stripes). The logo appears in the navbar next to your project name with automatic Next.js Image optimization.

Auto-Generated Config

When you run nexus-docs init, the CLI automatically:

1. Reads your package.json (name, description)
2. Creates nexus-docs.config.json with sensible defaults
3. Copies default Nexus logo to .fumadocs/public/logo.png
4. Generates all templates with your config values replaced

📝 Best Practices

Documentation Structure

✅ Good Structure
docs/
├── index.mdx              # Clear homepage
├── getting-started/       # Logical grouping
├── guides/
└── api/

❌ Avoid
docs/
├── doc1.mdx              # Non-descriptive names
├── doc2.mdx
└── random-stuff.mdx

MDX Files

✅ Good
---
title: Clear Title
description: Helpful description
---

# Clear Title

Well-organized content with sections...

❌ Avoid
# Random title that doesn't match frontmatter
No description, unclear structure...

Git Practices

# ✅ Commit docs/ folder with config and env template
git add docs/
git add docs/nexus-docs.config.json
git add docs/.env.example

# ✅ Ignore .nexusdocs/ (generated) and secrets
echo ".nexusdocs/" >> .gitignore
echo "docs/.env.local" >> .gitignore

# ❌ Don't commit .nexusdocs/ or secrets
git add .nexusdocs/  # NO!
git add docs/.env.local  # NO!

🎓 Migration Guide

From Docusaurus

# 1. Copy your docs
cp -r docusaurus/docs ./docs

# 2. Initialize
nexus-docs init

# 3. Adjust frontmatter if needed
# Docusaurus and Fumadocs use similar formats

# 4. Serve
nexus-docs serve

From MkDocs

# 1. Convert YAML to MDX frontmatter
# (may need manual conversion)

# 2. Copy markdown files to docs/
cp -r mkdocs/docs ./docs

# 3. Initialize
nexus-docs init

# 4. Serve
nexus-docs serve

From GitBook

# 1. Export GitBook content

# 2. Convert to MDX format

# 3. Initialize
nexus-docs init

# 4. Serve
nexus-docs serve

🔗 Integration Examples

With Monorepo

my-monorepo/
├── packages/
│   ├── core/
│   ├── ui/
│   └── utils/
├── docs/              # ← Single docs folder for entire monorepo
│   ├── packages/
│   │   ├── core.mdx
│   │   ├── ui.mdx
│   │   └── utils.mdx
│   └── guides/
└── .fumadocs/        # ← Generated at root

With Backend Project

my-backend/
├── src/              # Go/Python/Java code
├── tests/
├── docs/             # ← API documentation
│   ├── index.mdx
│   ├── api/
│   └── deployment/
└── .fumadocs/

With Mobile App

my-mobile-app/
├── ios/
├── android/
├── docs/             # ← App documentation
│   ├── setup.mdx
│   ├── features/
│   └── api/
└── .fumadocs/

🎯 Use Cases

Open Source Projects

Perfect for documenting libraries, tools, and frameworks.

API Documentation

Document your REST/GraphQL APIs with interactive examples.

Internal Documentation

Team wikis, onboarding guides, and process documentation.

Product Documentation

User guides, tutorials, and help centers.

Technical Writing

Blog posts, tutorials, and educational content.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md.

📄 License

MIT © OPLOG

🔗 Resources

• Fumadocs Documentation
• Fumadocs GitHub
• Example Projects
• Video Tutorials

💬 Support

• 📧 Email: [email protected]
• 💬 Discord: OPLOG Community
• 🐛 Issues: GitHub Issues
• 📖 Docs: docs.oplog.com

Make documentation easy. Add /docs, run nexus-docs init, and you're done! ✨