insertr/README.md

# Insertr

> **The Tailwind of CMS** - Zero-configuration content editing for any static site

Insertr adds editing capabilities to any HTML website by simply adding `class="insertr"` to elements. No complex setup, no architectural changes, no framework dependencies. Just mark what should be editable and get a production-ready CMS.

## ✨ Zero Configuration Philosophy

### **Just Add a Class**
```html
<!-- Individual elements -->
<h1 class="insertr">Main Title</h1>
<p class="insertr">Description text</p>  
<a href="/contact" class="insertr">Contact Us</a>

<!-- Container expansion -->
<section class="insertr">
  <h1>Hero Title</h1>
  <p>Hero description</p>
  <button>Call to Action</button>
</section>
```

**That's it!** No manual IDs, no configuration files, no schema definitions.

### **Container Expansion**
Containers with `class="insertr"` automatically make their viable children editable:
- **Viable children**: Elements containing only text (h1-h6, p, span, a, button)
- **Automatic detection**: Skip complex nested elements
- **Semantic convenience**: One class enables section-wide editing

## 🎯 Three User Experiences

### 1. **Regular Visitors** (99% of traffic)
- Pure static HTML performance
- Zero editor assets loaded
- No runtime overhead

### 2. **Content Editors** (Authenticated users)
- Rich editing interface loads on demand
- Click-to-edit any marked element
- Smart input types: text, textarea, link editor, markdown
- Changes saved to database

### 3. **Developers** (You)
- Add `class="insertr"` to any element
- Use HTML `id` attributes for complex cases
- Never see or manage generated content IDs
- Works with any static site generator

## 🚀 Current Status

**✅ Go CLI Parser Complete**
- **Container expansion**: `div.insertr` auto-expands to viable children
- **Smart content detection**: Automatic text/markdown/link classification  
- **ID generation**: Context-aware, collision-resistant identifiers
- **Development server**: Live reload with Air integration

**🔄 In Development**
- Content injection engine (database → HTML)
- Smart asset loading (editor only for authenticated users)
- Production deployment examples

## 🛠️ Quick Start

### **Using Just (Recommended)**
```bash
# Clone and setup
git clone <repository-url>
cd insertr

# Install dependencies and start development
just dev-setup

# Or step by step:
just install       # Install all dependencies
just build-lib     # Build the JavaScript library
just dev           # Start development server
```

### **Using NPM directly**
```bash
# Clone repository
git clone <repository-url>
cd insertr

# Install dependencies
npm run install:all

# Start development server with live reload
npm run dev
```

Visit **http://localhost:3000** to see enhanced demo site with live reload.

### **Available Commands**
```bash
just --list        # Show all available commands
just dev           # Start development server
just build         # Build library + CLI  
just air           # Start Air hot-reload for CLI
just check         # Validate project setup
just clean         # Clean build artifacts
```

### **Parse Existing Site**
```bash
# Analyze HTML for editable elements
just parse
# or: cd insertr-cli && go run main.go parse ../demo-site/

# Development server with parsing
just servedev
# or: cd insertr-cli && go run main.go servedev -i ../demo-site -p 3000
```

## 📊 Parser Output Example

```bash
🔍 Parsing HTML files in: ../demo-site/

📊 Parse Results:
   Files processed: 2
   Elements found: 40
   Container expansions: 3
   Generated IDs: 34

📝 Content Types:
   text: 19      # Headlines, short content
   markdown: 19  # Rich content, paragraphs  
   link: 2       # Buttons, navigation

🎯 Container Expansions:
   hero-section → 3 children (h1, p, button)
   services-grid → 6 children (3×h3, 3×p)
```

## 🏗️ Architecture: Build-Time Enhancement

### **Enhancement Pipeline**
```
Static Site Build → Insertr CLI Enhancement → Enhanced Deployment
     ↓                       ↓                       ↓
  Pure HTML            Parse + Inject Content    Smart Loading
                       Auto-generate IDs          (Auth-dependent)
```

### **Smart Loading Strategy**
```html
<!-- Regular visitors: zero overhead -->
<h1 class="insertr">Welcome to Our Site</h1>

<!-- Authenticated editors: rich editing -->
<h1 class="insertr" data-content-id="hero-title-abc123" 
    data-editor-loaded="true">Latest Content From Database</h1>
```

**Benefits:**
- **Performance**: Zero runtime cost for regular visitors
- **Framework agnostic**: Works with Hugo, Next.js, Jekyll, etc.
- **Zero configuration**: No schema files or content mappings
- **Developer friendly**: Stay in HTML markup, no context switching

## 📚 Integration Examples

### **GitHub Actions Workflow**
```yaml
# .github/workflows/deploy.yml
- name: Build static site
  run: hugo --minify

- name: Enhance with Insertr
  run: insertr enhance ./public --output ./dist

- name: Deploy enhanced site
  uses: peaceiris/actions-gh-pages@v3
  with:
    publish_dir: ./dist
```

### **Container vs Individual Elements**
```html
<!-- Semantic convenience: entire section editable -->
<section id="hero" class="insertr">
  <h1>Dynamic Title</h1>           <!-- → text input -->
  <p>Dynamic description</p>       <!-- → textarea -->  
  <button>Dynamic CTA</button>     <!-- → link editor -->
</section>

<!-- Granular control: specific elements -->
<nav>
  <h1 class="insertr">Site Name</h1>
  <ul>
    <li><a href="/" class="insertr">Home</a></li>
    <li><a href="/about" class="insertr">About</a></li>
  </ul>
</nav>
```

### **Content Type Detection**
- **Headlines** (`h1-h6`) → Text input with character limits
- **Paragraphs** (`p`) → Markdown textarea for rich content  
- **Links/Buttons** (`a`, `button`) → Text + URL fields
- **Containers** (`div`, `section`) → Expand to viable children

## 🔧 Development Workflow

### **Live Development with Hot Reload**
```bash
# 🔥 Hot Reload: watches BOTH library AND CLI
just air
# or: cd insertr-cli && air

# Alternative: Watch library only
just watch
# or: cd lib && npm run dev

# Library changes: lib/src/**/*.js → Auto rebuild library + CLI
# CLI changes: cmd/**/*.go → Auto rebuild CLI  
# Both trigger server restart with latest embedded assets
# Visit localhost:3000 → Refresh to see changes
```

**What Gets Hot Reloaded:**
- JavaScript library changes (`lib/src/`)
- Go CLI changes (`insertr-cli/`)  
- Enhanced HTML output (real-time content injection)

### **Content ID Management**
**Development Phase:**
- Generated IDs are disposable and change freely
- Focus on markup, ignore content persistence
- Use HTML `id` attributes for complex cases

**Production Phase:**
- Preserve existing content mappings for stability  
- CLI warns about orphaned content
- Simple migration tools for structural changes

## 📖 Documentation

- **[Development Guide](DEVELOPMENT.md)** - Setup and contribution workflow
- **[Research Document](RESEARCH.md)** - Strategic analysis and market positioning
- **[Parser Documentation](insertr-cli/README.md)** - CLI usage and API reference

## 🎯 Market Position: "The Tailwind of CMS"

**Tailwind CSS Approach:**
- Utility-first classes: `class="text-lg font-bold"`
- Zero configuration, build-time optimization
- Framework agnostic, developer workflow integration

**Insertr CMS Approach:**
- Content-first classes: `class="insertr"`  
- Zero configuration, build-time enhancement
- Framework agnostic, developer workflow integration

**Shared Principles:**
- Stay in markup, don't context switch
- Build-time optimization, zero runtime overhead
- Works with any framework or generator
- Developer experience focused

## 🤝 Contributing

This project follows the "Tailwind philosophy" of developer-first design:

1. **Zero configuration** - Markup-driven approach
2. **Build-time optimization** - No runtime performance cost
3. **Framework agnostic** - Works with any tech stack  
4. **Developer friendly** - Minimal cognitive overhead

See [DEVELOPMENT.md](DEVELOPMENT.md) for technical setup and contribution guidelines.

## 📄 License

MIT License - see LICENSE file for details.

---

**Built with ❤️ for developers who want powerful editing without the complexity**