insertr/README.md

# Insertr

> **Element-Level Edit-in-place CMS** - Hybrid approach with individual elements and markdown collections

Insertr allows developers to make any website content editable by simply adding a CSS class. Clients get appropriate editing interfaces based on content type - individual fields for headlines/buttons, rich markdown editors for flowing content.

## ✨ Two Editing Approaches

### **Element-Level Editing** (Granular Control)
```html
<h1 class="insertr" data-content-id="headline">Main Title</h1>
<p class="insertr" data-content-id="subtitle">Short description</p>
<a class="btn-primary insertr" data-content-id="cta">Get Started</a>
```

Perfect for:
- Headlines, titles, taglines
- Call-to-action buttons (text + URL)
- Contact information
- Short descriptions

### **Markdown Collections** (Rich Content)
```html
<div class="insertr" data-content-id="story" data-field-type="markdown">
  <p>Our company was founded in 2020...</p>
  <p>We recognized that **small businesses** needed access to...</p>
  <p>Today, we've helped over [200 clients](portfolio) achieve their goals.</p>
</div>
```

Perfect for:
- Story sections, articles
- Team member bios  
- Product descriptions
- Multi-paragraph content with formatting

**That's it!** Your clients get the right editing experience for each content type.

## 🎯 Three User Types

### 1. **The Customer** (End User)
- Sees a clean, professional website
- No editing interface visible
- Fast loading with minimal overhead

### 2. **The Client** (Content Manager)  
- Logs in to see the same website with subtle edit buttons
- Gets appropriate editing interfaces:
  - **Text inputs** for headlines and short content
  - **Link editors** for buttons (text + URL fields)
  - **Markdown editors** for rich content with formatting
- Changes are saved immediately with responsive overlay forms

### 3. **The Developer** (You)
- **Element-level**: Add `class="insertr"` to any individual element
- **Markdown collections**: Add `data-field-type="markdown"` for rich content
- No complex setup or framework dependencies
- Works with any existing website

## 🚀 Current Status

**✅ Frontend Prototype Complete**
- **Hybrid editing system**: Element-level + markdown collections
- **Smart field detection**: Automatic input types based on HTML tags
- **Responsive overlay forms**: Width adapts to element size
- **Markdown support**: Powered by marked.js for rich content
- **Mock authentication system** with role switching
- **Local persistence** with automatic saving
- **Multi-page support** with consistent experience

**🔄 In Development**
- Go backend with REST API
- Authentik OAuth integration
- File-based content storage
- Git version control

## 🛠️ Quick Start

1. **Clone and install**:
   ```bash
   git clone <repository-url>
   cd insertr
   npm install
   ```

2. **Start development server**:
   ```bash
   npm run dev
   ```

3. **Open http://localhost:3000** and test the demo!

## 📚 Integration Guide

### Basic Setup
```html
<!-- Include required dependencies -->
<script src="https://cdn.jsdelivr.net/npm/marked@16.2.1/lib/marked.umd.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dompurify@3.0.5/dist/purify.min.js"></script>

<!-- Include Insertr modules -->
<link rel="stylesheet" href="insertr/insertr.css">
<script src="insertr/config.js"></script>
<script src="insertr/validation.js"></script>
<script src="insertr/form-renderer.js"></script>
<script src="insertr/content-manager.js"></script>
<script src="insertr/markdown-processor.js"></script>
<script src="insertr/insertr.js"></script>
```

### Element-Level Editing
```html
<!-- Headlines get text input -->
<h1 class="insertr" data-content-id="main-title">Your Title</h1>

<!-- Paragraphs get textarea -->  
<p class="insertr" data-content-id="description">Your description</p>

<!-- Buttons get text + URL fields -->
<a href="/contact" class="btn-primary insertr" data-content-id="cta">Contact Us</a>
```

### Markdown Collections
```html
<!-- Rich content gets markdown editor -->
<div class="insertr" data-content-id="story" data-field-type="markdown">
  <p>Your story begins here...</p>
  <p>Use **bold**, *italic*, and [links](url) naturally.</p>
  <p>Line breaks create new paragraphs automatically.</p>
</div>
```

### Field Types
- `<h1-h6>.insertr` → Text input with appropriate length limits
- `<p>.insertr` → Textarea (larger for `.lead` paragraphs)  
- `<a>.insertr` → Link editor with text and URL fields
- `<div data-field-type="markdown">` → Large markdown editor with formatting support

## 📖 Documentation

- **[Development Guide](DEVELOPMENT.md)** - Setup, workflow, and contribution guide
- **[Demo Instructions](demo-site/README.md)** - How to test the prototype
- **[Project Planning](INITIAL.md)** - Requirements, research, and roadmap

## 🏗️ Architecture

### Current (Phase 1)
- **Frontend**: Vanilla JavaScript with marked.js for markdown
- **Editing**: Hybrid element-level + markdown collection system
- **Storage**: localStorage (for prototype)
- **Authentication**: Mock system
- **Deployment**: Static files

### Planned (Phase 2)
- **Backend**: Go HTTP server
- **Storage**: File-based with Git versioning  
- **Authentication**: Authentik OAuth 2.0
- **Deployment**: Single binary + static files

### Future (Phase 3)
- **Multi-tenant**: Host multiple client sites
- **Admin Dashboard**: Advanced content management
- **CDN Integration**: Global content delivery
- **Plugin System**: Extensible functionality

## 🎬 Demo Features

**Try the prototype to see:**
- ✏️ **Element-Level Editing** - Individual text inputs for headlines, textareas for paragraphs, link editors for buttons
- 📝 **Markdown Collections** - Large editor for rich content with **bold**, *italic*, [links], line breaks → paragraphs
- 🎯 **Smart Field Detection** - Automatic input types based on HTML tags and classes
- 📏 **Responsive Overlays** - Edit forms resize to match element width
- 👤 **Authentication** - Login simulation with role switching
- 💾 **Persistence** - Content saves automatically with localStorage
- 🔄 **Multi-page** - Consistent experience across pages (index.html + about.html)

## 🤝 Contributing

This project is in active development. See [DEVELOPMENT.md](DEVELOPMENT.md) for:
- Development setup
- Project structure
- Testing guidelines
- Future roadmap

## 📄 License

MIT License - see LICENSE file for details.

---

**Built with ❤️ for small business websites and their developers**