File2Site

A zero-config CLI that turns a single Markdown, HTML, JSON, or YAML file into a beautiful live website with advanced features.

Quick Start

npx file2site README.md

Features

Core Features

• 🚀 Zero Configuration - No config files needed
• 📝 Multiple Formats - Markdown, HTML, JSON, YAML, and text files
• 🔄 Live Reload - Instant browser refresh on file saves with auto-reconnect
• 🌐 Auto Browser Launch - Opens automatically (disable with --no-open)
• 📱 QR Code - Easy mobile access with --qr flag

Enhanced Markdown

• ✨ Syntax Highlighting - Code blocks with highlight.js
• 📑 Table of Contents - Auto-generated with [[toc]]
• ✅ Task Lists - GitHub-style checkboxes
• 🔗 Smart Links - External links open in new tab
• 🎯 Anchor Links - Auto-generated heading anchors
• 📊 Mermaid Diagrams - Built-in diagram support
• 🔢 Math Equations - KaTeX support for formulas

Security

• 🔒 HTML Sanitization - XSS protection for user content
• 🛡️ CSP Headers - Content Security Policy enabled
• 🚫 Path Validation - Protection against directory traversal

Customization

• 🎨 Custom CSS - Inject your own styles with --css
• 🌓 Dark Mode - Built-in theme toggle with --dark-mode
• ⚡ Performance - Intelligent caching for faster renders
• ⏱️ Configurable Debounce - Adjust watch sensitivity with --debounce

Export Options

• 📄 HTML Export - Generate standalone HTML files
• 📑 PDF Export - Create PDFs with --export-pdf

Developer Experience

• 📊 Verbose Mode - Detailed logging with --verbose
• 🔄 Port Retry - Automatic port conflict resolution
• 🎯 TypeScript - Full type safety
• 🧪 Tested - Comprehensive test suite

CLI

file2site <file> [options]

Options

• --port <number> - Use a specific port (finds alternative if taken)
• --no-open - Don't open browser automatically
• --export - Export static HTML and exit
• --export-pdf - Export PDF (requires --port)
• --css <file> - Path to custom CSS file
• --dark-mode - Enable dark mode toggle button
• --debounce <ms> - File watch delay (default: 80ms)
• --verbose - Enable detailed logging
• --qr - Show QR code for mobile access

Examples

# Basic usage
file2site README.md

# Custom port with dark mode
file2site docs.md --port 3000 --dark-mode

# Export with custom styles
file2site page.md --export --css custom.css

# PDF export
file2site report.md --export-pdf --port 8080

# Mobile development with QR code
file2site app.html --qr --no-open

# Verbose mode for debugging
file2site config.json --verbose

Use Cases

• 📚 Documentation Preview - See docs as they'll appear
• 🎨 Quick Landing Pages - Single markdown to website
• 🔧 HTML Prototypes - Share demos without frameworks
• 📱 Mobile Testing - QR codes for easy device access
• 📊 Data Visualization - Pretty-print JSON/YAML
• 📝 README Walkthroughs - Production-ready previews
• 📄 Report Generation - Markdown to PDF workflows

Advanced Features

Mermaid Diagrams

\`\`\`mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
\`\`\`

Math Equations

Inline: $E = mc^2$

Block:
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Custom Styling

# Create custom.css
echo "body { font-family: 'Comic Sans MS'; }" > custom.css

# Use it
file2site README.md --css custom.css

Non-Goals

• ❌ Multiple pages or routing
• ❌ Build-time configuration files
• ❌ Framework integration
• ❌ Hosting or deployment features

Technical Details

Security

• HTML Sanitization - All user HTML is sanitized using sanitize-html
• CSP Headers - Strict Content Security Policy
• Path Validation - Prevents directory traversal attacks
• XSS Protection - Multiple layers of protection

Performance

• Intelligent Caching - Rendered content cached until file changes
• Efficient Watching - Debounced file system monitoring
• Lazy Loading - Resources loaded on demand

Export Details

• --export writes file.html for Markdown inputs
• Non-Markdown files get .file2site.html suffix to avoid overwriting
• --export-pdf uses Puppeteer for high-quality PDF generation
• Exported files include all styles inline for portability

Supported Extensions

• .md - Markdown with full feature support
• .html - HTML with sanitization
• .json - Syntax highlighted JSON
• .yaml, .yml - Syntax highlighted YAML
• .txt - Plain text in code blocks

Development

# Install dependencies
npm install

# Run in development mode
npm run dev -- README.md

# Run tests
npm test

# Run tests with UI
npm run test:ui

# Build
npm run build

# Type check
npm run typecheck

License

MIT