Folder-Site

One-command local website generator for documentation and knowledge bases

✨ Features

Folder-Site CLI is a powerful command-line tool that transforms any directory into a browsable website, providing a VS Code-like experience for local documentation, knowledge bases, and Workhub integration.

Core Features

• 🚀 One-command Launch - Start a local server with a single command
• 📁 File Tree Navigation - Expandable/collapsible directory tree
• 📝 Markdown Rendering - Full GFM support with syntax highlighting
• 🔍 Fast Search - Cmd+P fuzzy file search (< 100ms)
• 🔄 Live Preview - Auto-refresh on file changes
• 🌓 Dark/Light Theme - Theme switching with persistence
• 🔌 Plugin System - Extensible renderer architecture

Advanced Features

• 📊 Chart Rendering - Mermaid, Graphviz, Vega support
• 🎨 Code Highlighting - 100+ languages (Shiki)
• 📄 Export - Client-side PDF/HTML export
• 🏢 Workhub Integration - docs/ structure support
• 👀 File Watching - Efficient monitoring via chokidar
• ⚡ Render Caching - LRU cache for performance
• ⌨️ Keyboard Shortcuts - Full keyboard navigation

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• Bun >= 1.0.0 (recommended)

Installation

# Using npm
npm install -g folder-site

# Using yarn
yarn global add folder-site

# Using pnpm
pnpm add -g folder-site

# Using bun
bun install -g folder-site

Basic Usage

# Start in current directory
folder-site

# Start in specified directory
folder-site /path/to/docs

# Specify port
folder-site --port 8080

# Show version
folder-site --version

# Show help
folder-site --help

Once the server starts, open http://localhost:3000 in your browser.

📖 Documentation

• Installation Guide - Detailed installation instructions
• Usage Guide - Complete usage documentation
• API Documentation - API interface documentation
• Troubleshooting - Common issues and solutions

Design documents are available in the docs/ directory.

🛠️ Tech Stack

Backend

| Technology | Purpose | |------------|---------| | Bun | Fast JavaScript runtime | | Hono | Lightweight web framework | | unified | Markdown processing pipeline | | remark | Markdown parser | | rehype | HTML converter | | chokidar | File watcher | | lru-cache | Cache implementation | | fuse.js | Fuzzy search |

Frontend

| Technology | Purpose | |------------|---------| | React | UI library | | Vite | Build tool | | Tailwind CSS | Styling framework | | Radix UI | Accessible components | | Shiki | Syntax highlighting | | jsPDF | PDF generation |

🏗️ Project Structure

folder-site/
├── src/
│   ├── cli/              # CLI entry point
│   ├── server/           # Hono server
│   │   ├── routes/       # API routes
│   │   ├── middleware/   # Middleware
│   │   ├── services/     # Business logic
│   │   └── lib/          # Core libraries
│   ├── client/           # React frontend
│   │   ├── components/   # React components
│   │   ├── pages/        # Page components
│   │   ├── hooks/        # Custom hooks
│   │   └── layouts/      # Layouts
│   ├── parsers/          # File parsers
│   ├── types/            # TypeScript types
│   └── utils/            # Utility functions
├── plugins/              # Plugin directory
│   ├── mermaid-renderer/ # Mermaid plugin
│   └── graphviz-renderer/# Graphviz plugin
├── public/               # Static assets
├── docs/                 # Documentation
├── tests/                # Test files
└── package.json

⌨️ Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Cmd+P / Ctrl+P | Quick file search | | Esc | Close modal | | ↑ / ↓ | Navigate results | | Enter | Open selected file | | Cmd+K / Ctrl+K | Toggle command palette | | Cmd+D / Ctrl+D | Toggle dark/light theme |

📁 Supported File Types

| Extension | Type | Renderer | |-----------|------|----------| | .md | Markdown | Built-in | | .mmd | Mermaid | Plugin | | .txt | Plain text | Built-in | | .json | JSON | Built-in | | .yml / .yaml | YAML | Built-in |

🔧 Configuration

Config File (.folder-siterc.json)

{
  "port": 3000,
  "theme": "dark",
  "sidebar": {
    "width": 280,
    "collapsed": false
  },
  "search": {
    "debounce": 50,
    "maxResults": 10
  },
  "cache": {
    "enabled": true,
    "ttl": 3600000
  }
}

Environment Variables

# Server port
PORT=3000

# Theme (light/dark)
THEME=dark

# Cache TTL (milliseconds)
CACHE_TTL=3600000

🤝 Contributing

Contributions are welcome! Please:

1. Read the design documents
2. Check existing issues
3. Create a feature branch
4. Submit a pull request

📄 License

MIT License - See LICENSE file

🙏 Acknowledgments

• markdown-viewer-extension - Markdown rendering inspiration
• Radix UI - Accessible components
• shadcn/ui - Beautiful component examples
• @react-symbols/icons - File/folder icons
• RemixIcon - General icons
• Vercel - Design inspiration

📞 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Ready to get started? → Quick Start Guide 🚀