Luffa

A modern, responsive documentation kit built with Next.js 15, Tailwind CSS, and MDX. Perfect for creating beautiful API documentation, guides, and technical documentation websites.

🌐 Visit us at luffa.dev

✨ Features

• Modern Stack: Built with Next.js 15.3.4, React 18, and TypeScript
• 🤖 AI-Powered Search: RAG (Retrieval-Augmented Generation) search with Upstash Vector
• 📝 MDX Support: Write documentation in Markdown with React components
• 🎨 Syntax Highlighting: Code blocks with Shiki highlighting support
• 🌙 Dark Mode: Built-in dark/light theme toggle
• 📱 Responsive Design: Mobile-first responsive design with Tailwind CSS
• 🔍 Dual Search: Traditional FlexSearch + AI-powered semantic search
• 📊 Navigation: Automatic navigation generation from file structure
• ⚡ Fast: Static site generation for optimal performance
• 🎨 Customizable: Easy to customize themes and extend functionality

🚀 Quick Start

# Clone the repository
git clone https://github.com/llamacto/luffa.git
cd luffa

# Install dependencies
npm install

# Set up environment variables (see Environment Setup below)
cp env.example .env.local

# Start development server
npm run dev

🔧 Environment Setup

Required for AI Search (RAG)

Create a .env.local file:

# Upstash Vector Database (Free: 10,000 vectors + 10,000 queries/month)
UPSTASH_VECTOR_REST_URL=https://your-vector-db-url.upstash.io
UPSTASH_VECTOR_REST_TOKEN=your_vector_token_here

# OpenAI API Key
OPENAI_API_KEY=sk-your_openai_api_key_here

Getting Started

1. Create Upstash Vector Database

   • Sign up at upstash.com
   • Create a Vector Database
   • Copy REST URL and Token

2. Get OpenAI API Key

   • Visit platform.openai.com
   • Create new API key

3. Sync Documentation

   npm run sync-docs

📖 Documentation Structure

src/
├── app/
│   ├── api-reference/
│   │   └── page.mdx          # API documentation
│   ├── guides/
│   │   ├── getting-started/
│   │   │   └── page.mdx      # Guide pages
│   │   └── advanced/
│   │       └── page.mdx
│   └── page.mdx              # Homepage
├── content/                   # Additional content (optional)
│   ├── tutorials/
│   └── examples/
docs/                         # External docs folder (optional)

🤖 AI Search Features

RAG Search (Recommended)

• Accuracy: High (based on actual documentation)
• Context: Provides relevant document sources with relevance scores
• Response: Contextually aware answers with source attribution
• Fallback: Automatically falls back to basic AI if RAG fails

Basic AI Search (Fallback)

• Accuracy: Medium (general knowledge about your product)
• Context: None
• Response: General knowledge-based answers

📊 Free Tier Limits

Using Upstash free tier:

Service	Free Limit	Perfect For
Vector Database	10,000 vectors + 10,000 queries/month	Documentation chunks
Redis	10MB + 10,000 commands/day	Search result caching
QStash	500 messages/month	Webhook notifications

OpenAI Free Tier: 3 requests/minute for embeddings (rate-limited in sync script)

🛠️ Available Scripts

# Development
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server

# Documentation Management
npm run sync-docs    # Sync MDX files to vector database

# Code Quality
npm run lint         # Run ESLint

🏗️ Architecture

📄 MDX Documents
    ↓
🔄 Sync Script (splits into chunks)
    ↓
🧠 OpenAI Embeddings
    ↓
🗄️ Upstash Vector Database
    ↓
🔍 User Search Query → Semantic Search → 🤖 AI Response + Sources

🎨 Customization

Theme Colors

Luffa includes a custom color palette inspired by natural fibers:

• Primary: Luffa green shades (luffa-50 to luffa-950)
• Accent: Warm orange shades (accent-50 to accent-950)

Edit tailwind.config.ts to customize colors.

Search Configuration

Edit src/app/api/rag-search/route.ts:

// Adjust number of search results
topK: 8, // Default is 5

// Change embedding model
model: 'text-embedding-3-large', // Higher accuracy, higher cost

Edit scripts/sync-docs.js:

// Adjust chunk size and overlap
const chunks = splitTextIntoChunks(doc.content, 1500, 300)

📈 Performance

• Build Size: ~163KB optimized
• Search Latency:
  • RAG Search: ~2-3 seconds
  • Basic AI: ~1-2 seconds
  • Traditional Search: <100ms

🚀 Deployment

Vercel (Recommended)

1. Fork this repository
2. Connect to Vercel
3. Add environment variables in Vercel dashboard
4. Deploy automatically
5. Run sync after deployment: npm run sync-docs

Other Platforms

1. Set environment variables
2. Build the project: npm run build
3. Deploy the .next folder
4. Run sync script to populate vector database

🔍 Search Modes

Users can toggle between two search modes in the AI search interface:

1. RAG Search: Searches your actual documentation using semantic similarity
2. Basic AI: General AI assistant for questions about your product

📚 Documentation Best Practices

1. Structure: Use clear headings and sections
2. Metadata: Include title, description, and tags in frontmatter
3. Content: Write comprehensive, clear explanations
4. Updates: Run npm run sync-docs after content changes
5. SEO: Include relevant keywords naturally

🔗 Tech Stack

• Framework: Next.js 15
• Styling: Tailwind CSS
• Content: MDX
• Search: FlexSearch + Upstash Vector
• AI: OpenAI GPT
• Syntax Highlighting: Shiki
• Animations: Framer Motion

📄 License

MIT License - see LICENSE.md for details.

Based on TailwindUI Protocol template with significant modifications and enhancements for the Luffa documentation platform.

🤝 Contributing

We welcome contributions! Please read our contributing guidelines and feel free to submit pull requests.

📞 Support

• GitHub Issues: Report bugs or request features
• Documentation: Full setup guide
• Discord: Join our community (coming soon)

---

Built with ❤️ for the documentation community