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

342
README.md
View File

@@ -1,186 +1,240 @@
# Insertr # 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 ```html
<h1 class="insertr" data-content-id="headline">Main Title</h1> <!-- Individual elements -->
<p class="insertr" data-content-id="subtitle">Short description</p> <h1 class="insertr">Main Title</h1>
<a class="btn-primary insertr" data-content-id="cta">Get Started</a> <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: **That's it!** No manual IDs, no configuration files, no schema definitions.
- Headlines, titles, taglines
- Call-to-action buttons (text + URL)
- Contact information
- Short descriptions
### **Markdown Collections** (Rich Content) ### **Container Expansion**
```html Containers with `class="insertr"` automatically make their viable children editable:
<div class="insertr" data-content-id="story" data-field-type="markdown"> - **Viable children**: Elements containing only text (h1-h6, p, span, a, button)
<p>Our company was founded in 2020...</p> - **Automatic detection**: Skip complex nested elements
<p>We recognized that **small businesses** needed access to...</p> - **Semantic convenience**: One class enables section-wide editing
<p>Today, we've helped over [200 clients](portfolio) achieve their goals.</p>
</div>
```
Perfect for: ## 🎯 Three User Experiences
- 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. ### 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) ### 3. **Developers** (You)
- Sees a clean, professional website - Add `class="insertr"` to any element
- No editing interface visible - Use HTML `id` attributes for complex cases
- Fast loading with minimal overhead - Never see or manage generated content IDs
- Works with any static site generator
### 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 ## 🚀 Current Status
**✅ Frontend Prototype Complete** **✅ Go CLI Parser Complete**
- **Hybrid editing system**: Element-level + markdown collections - **Container expansion**: `div.insertr` auto-expands to viable children
- **Smart field detection**: Automatic input types based on HTML tags - **Smart content detection**: Automatic text/markdown/link classification
- **Responsive overlay forms**: Width adapts to element size - **ID generation**: Context-aware, collision-resistant identifiers
- **Markdown support**: Powered by marked.js for rich content - **Development server**: Live reload with Air integration
- **Mock authentication system** with role switching
- **Local persistence** with automatic saving
- **Multi-page support** with consistent experience
**🔄 In Development** **🔄 In Development**
- Go backend with REST API - Content injection engine (database → HTML)
- Authentik OAuth integration - Smart asset loading (editor only for authenticated users)
- File-based content storage - Production deployment examples
- Git version control
## 🛠️ Quick Start ## 🛠️ Quick Start
1. **Clone and install**: ### **Development Setup**
```bash ```bash
git clone <repository-url> # Clone repository
cd insertr git clone <repository-url>
npm install cd insertr
```
2. **Start development server**: # Start development server with live reload
```bash cd insertr-cli
npm run dev air
```
3. **Open http://localhost:3000** and test the demo!
## 📚 Integration Guide
### Basic Setup
```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>
<!-- 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>
``` ```
### Element-Level Editing Visit **http://localhost:3000** to see enhanced demo site with live reload.
```html
<!-- Headlines get text input -->
<h1 class="insertr" data-content-id="main-title">Your Title</h1>
<!-- Paragraphs get textarea --> ### **Parse Existing Site**
<p class="insertr" data-content-id="description">Your description</p> ```bash
cd insertr-cli
<!-- Buttons get text + URL fields --> # Analyze HTML for editable elements
<a href="/contact" class="btn-primary insertr" data-content-id="cta">Contact Us</a> go run main.go parse ../demo-site/
# Development server with parsing
go run main.go servedev -i ../demo-site -p 3000
``` ```
### Markdown Collections ## 📊 Parser Output Example
```html
<!-- Rich content gets markdown editor --> ```bash
<div class="insertr" data-content-id="story" data-field-type="markdown"> 🔍 Parsing HTML files in: ../demo-site/
<p>Your story begins here...</p>
<p>Use **bold**, *italic*, and [links](url) naturally.</p> 📊 Parse Results:
<p>Line breaks create new paragraphs automatically.</p> Files processed: 2
</div> 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)
``` ```
### Field Types ## 🏗️ Architecture: Build-Time Enhancement
- `<h1-h6>.insertr` → Text input with appropriate length limits
- `<p>.insertr` → Textarea (larger for `.lead` paragraphs) ### **Enhancement Pipeline**
- `<a>.insertr` → Link editor with text and URL fields ```
- `<div data-field-type="markdown">` → Large markdown editor with formatting support Static Site Build → Insertr CLI Enhancement → Enhanced Deployment
↓ ↓ ↓
Pure HTML Parse + Inject Content Smart Loading
Auto-generate IDs (Auth-dependent)
```
### **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
## 📚 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**
```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
```
### **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 ## 📖 Documentation
- **[Development Guide](DEVELOPMENT.md)** - Setup, workflow, and contribution guide - **[Development Guide](DEVELOPMENT.md)** - Setup and contribution workflow
- **[Demo Instructions](demo-site/README.md)** - How to test the prototype - **[Research Document](RESEARCH.md)** - Strategic analysis and market positioning
- **[Project Planning](INITIAL.md)** - Requirements, research, and roadmap - **[Parser Documentation](insertr-cli/README.md)** - CLI usage and API reference
## 🏗️ Architecture ## 🎯 Market Position: "The Tailwind of CMS"
### Current (Phase 1) **Tailwind CSS Approach:**
- **Frontend**: Vanilla JavaScript with marked.js for markdown - Utility-first classes: `class="text-lg font-bold"`
- **Editing**: Hybrid element-level + markdown collection system - Zero configuration, build-time optimization
- **Storage**: localStorage (for prototype) - Framework agnostic, developer workflow integration
- **Authentication**: Mock system
- **Deployment**: Static files
### Planned (Phase 2) **Insertr CMS Approach:**
- **Backend**: Go HTTP server - Content-first classes: `class="insertr"`
- **Storage**: File-based with Git versioning - Zero configuration, build-time enhancement
- **Authentication**: Authentik OAuth 2.0 - Framework agnostic, developer workflow integration
- **Deployment**: Single binary + static files
### Future (Phase 3) **Shared Principles:**
- **Multi-tenant**: Host multiple client sites - Stay in markup, don't context switch
- **Admin Dashboard**: Advanced content management - Build-time optimization, zero runtime overhead
- **CDN Integration**: Global content delivery - Works with any framework or generator
- **Plugin System**: Extensible functionality - Developer experience focused
## 🎬 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 ## 🤝 Contributing
This project is in active development. See [DEVELOPMENT.md](DEVELOPMENT.md) for: This project follows the "Tailwind philosophy" of developer-first design:
- Development setup
- Project structure 1. **Zero configuration** - Markup-driven approach
- Testing guidelines 2. **Build-time optimization** - No runtime performance cost
- Future roadmap 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 ## 📄 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 ## Strategic Recommendations
### 1. Market Positioning: "The Tailwind of CMS" ### 1. Market Positioning: "The Tailwind of CMS"