joakim/insertr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete library cleanup and documentation overhaul

Browse Source 
## Library Code Cleanup (~1,200+ lines removed)
- Remove legacy markdown system (markdown.js, previewer.js)
- Delete unused EditContext code from ui/editor.js (~400 lines)
- Remove version history UI components from form-renderer.js (~180 lines)
- Clean unused CSS styles from insertr.css (~120 lines)
- Update package.json dependencies (remove marked, turndown)

## Documentation Updates
- README.md: Update from markdown to HTML-first approach
- AGENTS.md: Add current architecture guidance and HTML-first principles
- TODO.md: Complete rewrite with realistic roadmap and current status
- demos/README.md: Update for development demo server usage

## System Reality Alignment
- All documentation now reflects current working system
- Removed aspirational features in favor of actual capabilities
- Clear separation between development and production workflows
- Accurate description of style-aware editor with HTML preservation

## Code Cleanup Benefits
- Simplified codebase focused on HTML-first approach
- Removed markdown conversion complexity
- Cleaner build process without unused dependencies
- Better alignment between frontend capabilities and documentation

Ready for Phase 3a server updates with clean foundation.
This commit is contained in:
Joakim
2025-09-20 00:02:03 +02:00
parent 63939e2c68
commit bb5ea6f873
14 changed files with 343 additions and 1982 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
README.md
View File

@@ -37,10 +37,11 @@ Containers with `class="insertr"` automatically make their viable children edita
- 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
- Style-aware editing interface loads on demand
- Click-to-edit any marked element
- Rich text editor with style preservation and formatting toolbar
- Link editor with popup configuration for complex elements
- Changes saved to database with version history
### 3. **Developers** (You)
- Add `class="insertr"` to any element
@@ -136,19 +137,23 @@ auth:
## 🚀 Current Status
**✅ Complete Full-Stack CMS**
- **Professional Editor**: Modal forms, markdown support, authentication system
- **Enterprise Authentication**: Production-ready OIDC integration with Authentik, PKCE security
- **Content Persistence**: SQLite database with REST API, version control
- **Style-Aware Editor**: Rich text editor with automatic style detection and formatting toolbar
- **HTML Preservation**: Perfect fidelity editing that maintains all element attributes and styling
- **Enterprise Authentication**: Production-ready OIDC integration with Authentik, PKCE security
- **Content Persistence**: SQLite/PostgreSQL database with REST API, complete 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
- **Smart Detection**: Auto-detects content types and generates style-based formatting options
- **Link Management**: Popup-based link configuration for complex multi-property elements
- **Full Integration**: Seamless development workflow with hot reload
**🚀 Production Ready**
- Deploy to cloud infrastructure
- Configure CDN for library assets
- Scale with PostgreSQL database
- ✅ Full HTTP API server with authentication and version control
- ✅ Build-time enhancement for static site generators
- ✅ PostgreSQL and SQLite database support
- ✅ Authentik OIDC integration for enterprise authentication
- Deploy enhanced static files to any CDN or host
- Run content API server on separate infrastructure
## 🛠️ Quick Start
@@ -166,8 +171,8 @@ just dev
```
This starts:
- **Demo site**: http://localhost:3000 (with live reload)
- **API server**: http://localhost:8080 (with content persistence)
- **Demo sites**: http://localhost:8080/sites/demo/ (auto-enhanced for testing)
- **API server**: http://localhost:8080/api/* (with content persistence and version control)
### **Using NPM**
```bash
@@ -202,10 +207,11 @@ just clean # Clean build artifacts
Running `just dev` gives you the **complete Insertr CMS**:
- ✅ **Professional Editor** - Modal forms, markdown support, authentication
- ✅ **Real-Time Persistence** - SQLite database with REST API
- ✅ **Style-Aware Editor** - Rich text editing with automatic style detection and formatting
- ✅ **HTML Preservation** - Perfect fidelity editing that maintains all styling and attributes
- ✅ **Real-Time Persistence** - SQLite database with REST API and authentication
- ✅ **Version Control** - Complete edit history with user attribution and rollback
- ✅ **Content Management** - Create, read, update content via browser
- ✅ **Content Management** - Create, read, update content via browser with popup-based link editing
- ✅ **Build Integration** - Binary enhances HTML with database content
- ✅ **Hot Reload** - Changes reflected immediately
@@ -309,18 +315,18 @@ just enhance input="src" output="public" # Custom paths
### **Runtime API Server**
```bash
# Development server with automatic site enhancement
./insertr serve --dev-mode --port 8080
# Production server with PostgreSQL
./insertr serve --db "postgresql://user:pass@host:5432/dbname"
./insertr serve --db "postgresql://user:pass@host:5432/dbname" --config production.yaml
# Development server with SQLite
./insertr serve --dev-mode --port 8080 --db ./dev.db
# Production server with custom config
# Production server with custom config and Authentik
./insertr --config ./production.yaml serve
# Use justfile shortcuts
just serve # Development server on :8080
just serve-prod port="443" # Production server
just serve # Development server on :8080 with auto-enhanced demo sites
just dev # Full development stack (recommended)
```
### **Configuration Options**
@@ -380,10 +386,10 @@ export INSERTR_SITE_ID="production"
```
### **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
- **Headlines** (`h1-h6`) → Rich text editor with style-aware formatting
- **Paragraphs** (`p`) → Rich text editor with detected style options from CSS
- **Links/Buttons** (`a`, `button`) → Popup-based link editor with text + URL configuration
- **Containers** (`div`, `section`) → Expand to viable children with automatic style detection
## 🔌 API Reference
@@ -512,81 +518,89 @@ mock_content: false # Use mock content instead of real data
- Works with any framework or generator
- Developer experience focused
## 🏗️ **Server-Hosted Static Sites** (NEW)
## 🚀 **Production Deployment Workflow**
**Real-time content updates for server-hosted static sites with immediate deployment.**
**Build-time enhancement + Runtime API for content management.**
### **Overview**
Insertr now supports hosting and enhancing static sites directly on the server. When content changes through the editor, static files are automatically updated in-place without requiring rebuilds or redeployment.
### **Production Architecture**
The production workflow separates content management from site hosting:
### **Key Benefits**
- ✅ **Immediate Updates**: Content changes are live instantly
- ✅ **Database Source of Truth**: Content stored in database, not files
- ✅ **No Rebuilds Required**: Only content updates, templates stay the same
- ✅ **Multi-Site Support**: Host multiple enhanced sites on one server
- ✅ **Automatic Backups**: Original files backed up before enhancement
### **Workflow**
```
1. Developer deploys static site → Server directory (e.g., /var/www/mysite)
2. Insertr enhances files → Adds editing capabilities + injects content
3. Editor makes changes → API updates database + triggers file enhancement
4. Changes immediately live → Visitors see updated content instantly
1. Static Site Build → `insertr enhance` → Enhanced Static Files → Deploy to CDN/Host
2. Content Editing → `insertr serve` API → Database → Triggers rebuild
```
### **Configuration Example**
```yaml
# insertr.yaml
server:
port: 8080
sites:
- site_id: "mysite"
path: "/var/www/mysite"
domain: "mysite.example.com"
auto_enhance: true
- site_id: "blog"
path: "/var/www/blog"
domain: "blog.example.com"
auto_enhance: true
```
### **Two-Server Architecture**
- **Content API Server**: Runs `insertr serve` for content management and authentication
- **Static Site Host**: Serves enhanced static files (CDN, GitHub Pages, Netlify, etc.)
### **Quick Start**
### **Production Workflow**
```bash
# 1. Configure sites in insertr.yaml
# 2. Start the server
./insertr serve --dev-mode
# 1. Build-time enhancement
./insertr enhance ./src --output ./dist --api https://cms.example.com
# 3. Your sites are automatically registered and enhanced
# 4. Content changes via editor immediately update static files
# 2. Deploy enhanced static files
rsync ./dist/ user@cdn:/var/www/site/
# 3. Run content API server (separate infrastructure)
./insertr serve --config production.yaml --db "postgresql://..."
```
### **Benefits**
- ✅ **Performance**: Static files served from CDN with zero CMS overhead
- ✅ **Scalability**: Content API and static hosting scale independently
- ✅ **Reliability**: Static site works even if CMS server is down
- ✅ **Security**: Content editing isolated from public site hosting
- ✅ **Framework Agnostic**: Works with any static site generator or CDN
### **Development Server** (Current Multi-Site Feature)
For development convenience, `insertr serve --dev-mode` can host multiple demo sites:
```yaml
# insertr.yaml (development only)
server:
sites:
- site_id: "demo"
path: "./demos/demo_enhanced"
source_path: "./demos/demo"
auto_enhance: true
```
This serves sites at `http://localhost:8080/sites/demo/` for testing the editor interface.
## ⚙️ Configuration
### **YAML Configuration (insertr.yaml)**
```yaml
# Global settings
dev_mode: false # Development mode features
# Database configuration
database:
path: "./insertr.db" # SQLite file path or PostgreSQL connection string
path: "./insertr.db" # SQLite file or PostgreSQL connection string
# Server configuration (with site hosting)
# Server configuration (multi-site hosting)
server:
port: 8080 # HTTP server port
sites: # Server-hosted static sites
- site_id: "demo"
path: "./demo-site"
domain: "localhost:3000"
auto_enhance: true
- site_id: "mysite"
path: "/var/www/mysite_enhanced" # Enhanced site output directory
source_path: "/var/www/mysite" # Original static site files
auto_enhance: true # Auto-enhance on startup and content changes
discovery:
enabled: false # Use explicit class="insertr" markings (true = auto-discover)
aggressive: false # Aggressive element discovery
# API configuration (for remote content API)
api:
url: "" # Content API URL (leave empty to use local database)
key: "" # API authentication key
# Build configuration (for CLI enhancement)
build:
input: "./src" # Default input directory for enhancement
# CLI enhancement configuration
cli:
site_id: "default" # Default site ID for CLI operations
output: "./dist" # Default output directory for enhanced files
inject_demo_gate: true # Inject demo editing gate if none exist
# API configuration (for CLI remote mode)
api:
url: "" # Content API URL (empty = use local database)
key: "" # API authentication key
# Authentication configuration
auth:
@@ -594,13 +608,9 @@ auth:
jwt_secret: "" # JWT signing secret (auto-generated in dev mode)
# Authentik OIDC configuration (production)
oidc:
endpoint: "https://auth.example.com/application/o/insertr/" # OIDC provider endpoint
client_id: "insertr-client" # OAuth2 client ID
client_secret: "your-secret" # Use AUTHENTIK_CLIENT_SECRET env var
# Global settings
site_id: "demo" # Default site ID for content lookup
mock_content: false # Use mock content instead of real data
endpoint: "" # https://auth.example.com/application/o/insertr/
client_id: "" # insertr-client (OAuth2 client ID)
client_secret: "" # OAuth2 client secret (or use AUTHENTIK_CLIENT_SECRET env var)
```
### **Environment Variables**