468 lines
14 KiB
Markdown
468 lines
14 KiB
Markdown
# 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
|
||
|
||
**✅ 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
|
||
- **Build 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)**
|
||
```bash
|
||
# 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**
|
||
```bash
|
||
# Alternative using npm
|
||
npm run install:all
|
||
npm run build
|
||
npm run dev
|
||
```
|
||
|
||
### **Available Commands**
|
||
```bash
|
||
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 serve # API server only (localhost:8080)
|
||
|
||
# Building
|
||
just build # Build library + unified binary (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** - Binary 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
|
||
```
|
||
|
||
|
||
|
||
## 📊 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: Unified Binary
|
||
|
||
### **Enhancement Pipeline**
|
||
```
|
||
Static Site Build → insertr enhance → Enhanced Deployment
|
||
↓ ↓ ↓
|
||
Pure HTML Parse + Inject Smart Loading
|
||
Database Content (Auth-dependent)
|
||
↓
|
||
Runtime Content API ← insertr serve ← Database (SQLite/PostgreSQL)
|
||
```
|
||
|
||
**Unified Commands:**
|
||
- `insertr enhance` - Build-time content injection
|
||
- `insertr serve` - Runtime API server
|
||
- Single binary handles both development and production workflows
|
||
|
||
### **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
|
||
|
||
## 🔧 Unified Binary Commands
|
||
|
||
### **Build-Time Enhancement**
|
||
```bash
|
||
# Production build with remote API
|
||
./insertr enhance src/ --output ./dist --api https://cms.example.com --api-key xyz
|
||
|
||
# Development build with local database
|
||
./insertr enhance demo-site/ --output ./dist --db ./content.db
|
||
|
||
# Development build with mock data
|
||
./insertr enhance demo-site/ --output ./dist --mock
|
||
|
||
# Use justfile shortcuts
|
||
just enhance # Default: demo-site/ → dist/ with mock data
|
||
just enhance input="src" output="public" # Custom paths
|
||
```
|
||
|
||
### **Runtime API Server**
|
||
```bash
|
||
# Production server with PostgreSQL
|
||
./insertr serve --db "postgresql://user:pass@host:5432/dbname"
|
||
|
||
# Development server with SQLite
|
||
./insertr serve --dev-mode --port 8080 --db ./dev.db
|
||
|
||
# Production server with custom config
|
||
./insertr --config ./production.yaml serve
|
||
|
||
# Use justfile shortcuts
|
||
just serve # Development server on :8080
|
||
just serve-prod port="443" # Production server
|
||
```
|
||
|
||
### **Configuration Options**
|
||
```bash
|
||
# YAML configuration file
|
||
./insertr --config ./custom.yaml [command]
|
||
|
||
# Environment variables
|
||
export INSERTR_DB_PATH="./content.db"
|
||
export INSERTR_API_URL="https://api.example.com"
|
||
export INSERTR_API_KEY="your-api-key"
|
||
export INSERTR_SITE_ID="production"
|
||
|
||
# Command-line flags (highest priority)
|
||
./insertr --db ./custom.db --site-id staging serve --port 3000
|
||
|
||
# Show all options
|
||
./insertr --help
|
||
./insertr enhance --help
|
||
./insertr serve --help
|
||
```
|
||
|
||
## 📚 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 unified binary
|
||
just air
|
||
|
||
# Alternative: Watch library only
|
||
just watch
|
||
# or: cd lib && npm run dev
|
||
|
||
# Library changes: lib/src/**/*.js → Auto rebuild library + binary
|
||
# Binary changes: cmd/**/*.go, internal/**/*.go → Auto rebuild binary
|
||
# 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 unified binary changes (`cmd/`, `internal/`)
|
||
- 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
|
||
- Binary warns about orphaned content
|
||
- Simple migration tools for structural changes
|
||
|
||
## ⚙️ Configuration
|
||
|
||
### **YAML Configuration (insertr.yaml)**
|
||
```yaml
|
||
# Database configuration
|
||
database:
|
||
path: "./insertr.db" # SQLite file or PostgreSQL connection string
|
||
|
||
# API configuration (for remote content API)
|
||
api:
|
||
url: "" # Content API URL (leave empty to use local database)
|
||
key: "" # API authentication key
|
||
|
||
# Server configuration
|
||
server:
|
||
port: 8080 # HTTP server port
|
||
dev_mode: false # Enable development mode features
|
||
|
||
# Build configuration
|
||
build:
|
||
input: "./src" # Default input directory
|
||
output: "./dist" # Default output directory
|
||
|
||
# Global settings
|
||
site_id: "demo" # Site ID for content lookup
|
||
mock_content: false # Use mock content instead of real data
|
||
```
|
||
|
||
### **Configuration Precedence**
|
||
1. **CLI flags** (highest priority) - `./insertr --db ./custom.db serve`
|
||
2. **Environment variables** - `INSERTR_DB_PATH=./custom.db`
|
||
3. **YAML config file** - `insertr.yaml` or `--config custom.yaml`
|
||
4. **Smart defaults** (lowest priority)
|
||
|
||
### **Environment Variables**
|
||
- `INSERTR_DB_PATH` - Database path
|
||
- `INSERTR_API_URL` - Remote API URL
|
||
- `INSERTR_API_KEY` - API authentication key
|
||
- `INSERTR_SITE_ID` - Site identifier
|
||
|
||
## 📖 Documentation
|
||
|
||
- **[Command Reference](COMMANDS.md)** - Complete command and configuration guide
|
||
- **[Development Guide](DEVELOPMENT.md)** - Setup and contribution workflow
|
||
- **[Research Document](RESEARCH.md)** - Strategic analysis and market positioning
|
||
- **[Integration Summary](INTEGRATION-SUMMARY.md)** - Complete architecture overview
|
||
|
||
## 🎯 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
|
||
|
||
## ⚙️ Configuration
|
||
|
||
### **YAML Configuration (insertr.yaml)**
|
||
```yaml
|
||
# Database configuration
|
||
database:
|
||
path: "./insertr.db" # SQLite file path or PostgreSQL connection string
|
||
|
||
# API configuration (for remote content API)
|
||
api:
|
||
url: "" # Content API URL (leave empty to use local database)
|
||
key: "" # API authentication key
|
||
|
||
# Server configuration
|
||
server:
|
||
port: 8080 # HTTP server port
|
||
dev_mode: false # Enable development mode features
|
||
|
||
# Build configuration
|
||
build:
|
||
input: "./src" # Default input directory for enhancement
|
||
output: "./dist" # Default output directory for enhanced files
|
||
|
||
# Global settings
|
||
site_id: "demo" # Default site ID for content lookup
|
||
mock_content: false # Use mock content instead of real data
|
||
```
|
||
|
||
### **Environment Variables**
|
||
- `INSERTR_DB_PATH` - Database path override
|
||
- `INSERTR_API_URL` - Remote API URL override
|
||
- `INSERTR_API_KEY` - API authentication key
|
||
- `INSERTR_SITE_ID` - Site identifier override
|
||
|
||
### **Configuration Precedence**
|
||
1. **CLI flags** (highest priority)
|
||
2. **Environment variables**
|
||
3. **YAML config file**
|
||
4. **Smart defaults** (lowest priority)
|
||
|
||
### **Database Options**
|
||
```bash
|
||
# SQLite (development)
|
||
./insertr serve --db "./content.db"
|
||
|
||
# PostgreSQL (production)
|
||
./insertr serve --db "postgresql://user:pass@host:5432/insertr"
|
||
|
||
# Environment-based
|
||
export INSERTR_DB_PATH="postgresql://prod-host/insertr"
|
||
./insertr serve
|
||
```
|
||
|
||
## 🤝 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** |