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

Update documentation to reflect Go CLI approach and ID generation philosophy

Browse Source 
- Rewrite README.md: Focus on Go CLI, container expansion, zero-config philosophy
- Add comprehensive ID generation strategy to RESEARCH.md
- Document two-phase approach: disposable dev IDs vs stable production mappings
- Explain edge cases, migration tools, and developer workflow
- Position as 'Tailwind of CMS' with build-time enhancement approach
This commit is contained in:
Joakim
2025-09-03 12:17:01 +02:00
parent 0e84af98bc
commit c2591e4fdd
2 changed files with 329 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

320
README.md
View File

@@ -1,186 +1,240 @@
# Insertr
> **Element-Level Edit-in-place CMS** - Hybrid approach with individual elements and markdown collections
> **The Tailwind of CMS** - Zero-configuration content editing for any static site
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.
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.
## ✨ Two Editing Approaches
## ✨ Zero Configuration Philosophy
### **Element-Level Editing** (Granular Control)
### **Just Add a Class**
```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>
<!-- 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>
```
Perfect for:
- Headlines, titles, taglines
- Call-to-action buttons (text + URL)
- Contact information
- Short descriptions
**That's it!** No manual IDs, no configuration files, no schema definitions.
### **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>
```
### **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
Perfect for:
- Story sections, articles
- Team member bios
- Product descriptions
- Multi-paragraph content with formatting
## 🎯 Three User Experiences
**That's it!** Your clients get the right editing experience for each content type.
### 1. **Regular Visitors** (99% of traffic)
- Pure static HTML performance
- Zero editor assets loaded
- No runtime overhead
## 🎯 Three User Types
### 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
### 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
### 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
**✅ 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
**✅ Go CLI Parser Complete**
- **Container expansion**: `div.insertr` auto-expands to viable children
- **Smart content detection**: Automatic text/markdown/link classification
- **ID generation**: Context-aware, collision-resistant identifiers
- **Development server**: Live reload with Air integration
**🔄 In Development**
- Go backend with REST API
- Authentik OAuth integration
- File-based content storage
- Git version control
- Content injection engine (database → HTML)
- Smart asset loading (editor only for authenticated users)
- Production deployment examples
## 🛠️ Quick Start
1. **Clone and install**:
### **Development Setup**
```bash
# Clone repository
git clone <repository-url>
cd insertr
npm install
# Start development server with live reload
cd insertr-cli
air
```
2. **Start development server**:
Visit **http://localhost:3000** to see enhanced demo site with live reload.
### **Parse Existing Site**
```bash
npm run dev
cd insertr-cli
# Analyze HTML for editable elements
go run main.go parse ../demo-site/
# Development server with parsing
go run main.go servedev -i ../demo-site -p 3000
```
3. **Open http://localhost:3000** and test the demo!
## 📊 Parser Output Example
## 📚 Integration Guide
```bash
🔍 Parsing HTML files in: ../demo-site/
### Basic Setup
📊 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**
```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>
<!-- Regular visitors: zero overhead -->
<h1 class="insertr">Welcome to Our Site</h1>
<!-- 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>
<!-- Authenticated editors: rich editing -->
<h1 class="insertr" data-content-id="hero-title-abc123"
data-editor-loaded="true">Latest Content From Database</h1>
```
### Element-Level Editing
**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**
```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
<!-- Headlines get text input -->
<h1 class="insertr" data-content-id="main-title">Your Title</h1>
<!-- 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>
<!-- 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>
<!-- 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>
```
### 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>
### **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**
```bash
cd insertr-cli
# Air watches Go files and rebuilds CLI
# Post-build: starts development server
air
# Edit parser code → Auto rebuild → Server restart
# Visit localhost:3000 → Refresh to see changes
```
### 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
### **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](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
- **[Development Guide](DEVELOPMENT.md)** - Setup and contribution workflow
- **[Research Document](RESEARCH.md)** - Strategic analysis and market positioning
- **[Parser Documentation](insertr-cli/README.md)** - CLI usage and API reference
## 🏗️ Architecture
## 🎯 Market Position: "The Tailwind of CMS"
### 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
**Tailwind CSS Approach:**
- Utility-first classes: `class="text-lg font-bold"`
- Zero configuration, build-time optimization
- Framework agnostic, developer workflow integration
### Planned (Phase 2)
- **Backend**: Go HTTP server
- **Storage**: File-based with Git versioning
- **Authentication**: Authentik OAuth 2.0
- **Deployment**: Single binary + static files
**Insertr CMS Approach:**
- Content-first classes: `class="insertr"`
- Zero configuration, build-time enhancement
- Framework agnostic, developer workflow integration
### 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)
**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 is in active development. See [DEVELOPMENT.md](DEVELOPMENT.md) for:
- Development setup
- Project structure
- Testing guidelines
- Future roadmap
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
@@ -188,4 +242,4 @@ MIT License - see LICENSE file for details.
---
**Built with ❤️ for small business websites and their developers**
**Built with ❤️ for developers who want powerful editing without the complexity**

131
RESEARCH.md
View File

@@ -433,6 +433,137 @@ CREATE TABLE content (
---
## Content ID Generation Strategy
### Philosophy: Zero Configuration with Pragmatic Stability
**Core Principle**: Developers should never think about content IDs unless they choose to.
#### Two-Phase Approach
**Development Phase (Pre-Production):**
- IDs are **completely disposable** and can change freely
- Generated using: `context-tag-hash` (e.g., `hero-h1-abc123ef`)
- Developers focus purely on markup: `<h1 class="insertr">Title</h1>`
- Only use HTML `id` attributes for complex stability requirements
**Production Phase (Post-Launch):**
- Preserve existing content mappings for stability
- CLI detects structural changes and warns about orphaned content
- Simple migration prompts for major refactoring
- Database tracks content lifecycle with "last seen" timestamps
#### ID Generation Algorithm
```go
func generateContentID(element) string {
context := nearestContext(element) // From HTML id or DOM position
tag := element.Tag // h1, p, button
hash := structureHash(element)[:8] // Element structure, not content
return fmt.Sprintf("%s-%s-%s", context, tag, hash)
}
```
**Context Resolution Priority:**
1. Nearest parent with HTML `id` attribute
2. Semantic section detection (header, main, aside, etc.)
3. DOM position fallback (section-0, div-1, etc.)
#### Edge Cases and Solutions
**1. Content Lifecycle Issues**
- **Orphaned Content**: Content exists in DB but element removed from HTML
- *Solution*: CLI warns + provides cleanup commands
- *Example*: `⚠️ Content 'hero-title-abc123' no longer found (last seen: 2024-09-01)`
- **Content Drift**: Element text changes, breaking content-dependent IDs
- *Solution*: IDs based on structure, not content text
- *Example*: `<h1>Welcome</h1>` → `<h1>About Us</h1>` keeps same ID
- **Duplicate Resolution**: Multiple elements generate same ID pattern
- *Solution*: Collision detection with incremental suffixes
- *Example*: `hero-h1-abc123`, `hero-h1-def456`
**2. Structural Changes**
- **Element Movement**: Same content, different DOM position
- *Solution*: HTML `id` attributes provide stability anchors
- *Example*: Moving `<h1>` between sections preserves ID if parent has `id`
- **Container Refactoring**: Switching between container vs individual `insertr` classes
- *Solution*: Parser detects structural changes and suggests migrations
- *Example*: `div.insertr` → individual child elements get mapped IDs
- **Framework Migrations**: Moving between SSGs changes HTML structure
- *Solution*: HTML `id` attributes survive framework changes
- *Content mapping*: Based on semantic meaning, not framework output
**3. Development Workflow Issues**
- **Branch Conflicts**: Multiple developers changing same elements
- *Solution*: Content stored separately from markup, no merge conflicts
- *Database approach*: Conflicts resolved at content level, not Git level
- **Content Staging**: Handling content across dev/staging/prod environments
- *Solution*: Environment-aware content API with fallbacks
- *Workflow*: Dev content → Staging approval → Production deployment
- **Reset Scenarios**: Starting fresh vs preserving existing content
- *Solution*: CLI provides reset/preserve options
- *Commands*: `insertr reset --preserve-content` vs `insertr reset --clean`
#### Migration and Maintenance Tools
**Content Mapping Detection**:
```bash
# Detect moved/renamed content with confidence scoring
insertr detect-changes --previous content-registry.json
⚠️ Potential content migrations detected:
hero-old-title → hero-main-title (95% confidence)
services-desc → about-story (12% confidence - manual review needed)
# Accept suggested migrations
insertr migrate hero-old-title hero-main-title
# Cleanup orphaned content
insertr cleanup --older-than 30d --confirm
```
**Developer Override System**:
```html
<!-- Explicit control when needed -->
<section id="hero">
<h1 class="insertr">Title</h1> <!-- Stable: hero-h1-* -->
<p class="insertr">Description</p> <!-- Stable: hero-p-* -->
</section>
<!-- Complex case: manual ID override -->
<h1 class="insertr" data-content-id="custom-stable-id">Special Case</h1>
```
#### Benefits of This Approach
**For Development:**
- Zero cognitive overhead for simple cases
- HTML `id` attributes provide escape hatch for complex scenarios
- Generated IDs invisible to developers in built output
- Fast iteration without content persistence concerns
**For Production:**
- Stable content mappings preserve editorial work
- Graceful handling of structural changes
- Clear migration paths for major refactoring
- Content lifecycle tracking prevents data loss
**For Content Editors:**
- Seamless editing experience regardless of ID complexity
- Content preserved across site restructures
- No exposure to technical ID management
This approach maintains the "zero configuration" philosophy while providing pragmatic solutions for production stability and content preservation.
---
## Strategic Recommendations
### 1. Market Positioning: "The Tailwind of CMS"