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)

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

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

   git clone <repository-url>
   cd insertr
   npm install
   

2. Start development server:

   npm run dev
   

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

📚 Integration Guide

Basic Setup

<!-- Include marked.js for markdown support -->
<script src="https://cdn.jsdelivr.net/npm/marked@16.2.1/lib/marked.umd.js"></script>
<!-- Include Insertr -->
<script src="insertr/insertr.js"></script>

Element-Level Editing

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

<!-- 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 - Setup, workflow, and contribution guide
• Demo Instructions - How to test the prototype
• Project Planning - 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 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