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

<!-- 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

✅ Complete Full-Stack CMS

• Professional Editor: Modal forms, markdown support, authentication system
• Content Persistence: SQLite database with REST API, version control
• Version History: Complete edit history with user attribution and one-click rollback
• CLI Enhancement: Parse HTML, inject database content, build-time optimization
• Smart Detection: Auto-detects content types (text/markdown/link)
• Deterministic IDs: Content-based ID generation for consistent developer experience
• Full Integration: Seamless development workflow with hot reload

🔄 Ready for Production

• Add authentication (JWT/OAuth)
• Deploy to cloud infrastructure
• Configure CDN for library assets

🛠️ Quick Start

Quick Start (Recommended)

# Clone and setup
git clone <repository-url>
cd insertr

# Install dependencies and build everything
just install build

# Start full-stack development
just dev

This starts:

• Demo site: http://localhost:3000 (with live reload)
• API server: http://localhost:8080 (with content persistence)

Using NPM

# Alternative using npm
npm run install:all
npm run build
npm run dev

Available Commands

just --list        # Show all available commands

# Development (Full-Stack by Default)
just dev           # Start full-stack development (recommended)
just demo-only     # Demo site only (no content persistence)
just server        # API server only (localhost:8080)

# Building  
just build         # Build library + CLI + server (complete stack)
just build-lib     # Build JavaScript library only

# Utilities
just check         # Validate project setup
just status        # Show project status
just clean         # Clean build artifacts

🎯 Complete Development Experience

Running just dev gives you the complete Insertr CMS:

• ✅ Professional Editor - Modal forms, markdown support, authentication
• ✅ Real-Time Persistence - SQLite database with REST API
• ✅ Version Control - Complete edit history with user attribution and rollback
• ✅ Content Management - Create, read, update content via browser
• ✅ Build Integration - CLI enhances HTML with database content
• ✅ Hot Reload - Changes reflected immediately

📚 Version Control Features

Complete Edit History

Every content change is automatically tracked with:

• User Attribution - Who made each change
• Timestamps - When changes were made
• Content Snapshots - Full content preserved for each version

Easy Rollback

• View History button in any content editor
• One-Click Restore to any previous version
• Version Comparison - See what changed between versions
• Safe Rollback - Current content is preserved before restoration

Example Workflow

1. Editor clicks on any element with class="insertr"
2. Professional editing modal opens
3. Click "View History" to see all previous versions
4. Each version shows: timestamp, author, content preview
5. Click "Restore" on any version to rollback instantly
6. All changes are tracked automatically

Parse Existing Site

# 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

🔍 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

<!-- 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

# .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

<!-- 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

# 🔥 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 - Setup and contribution workflow
• Research Document - Strategic analysis and market positioning
• Parser Documentation - 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 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