insertr/INSERTR-CONTENT-FEATURE.md

# .insertr-content Feature Specification

**Status**: Design Phase  
**Version**: 0.1.0  
**Last Updated**: October 16, 2025

## Executive Summary

The `.insertr-content` feature extends Insertr's CMS capabilities to handle long-form, complex content like blog posts and articles. While `.insertr` handles individual elements and `.insertr-add` manages collections, `.insertr-content` provides a rich text editing experience for larger content blocks that require sophisticated formatting, structure, and content management workflows.

## Current State Analysis

### Existing Insertr Architecture
- **StyleAwareEditor**: Rich text editing with automatic style detection
- **HTML Preservation Engine**: Perfect fidelity editing maintaining all attributes  
- **Style Detection Engine**: Converts nested elements to formatting options
- **Collection Management**: `.insertr-add` for dynamic content collections
- **Static Site Enhancement**: Build-time content injection and file processing

### Gaps for Blog/Article Content
- No unified interface for long-form content editing
- Limited content structure management (headings, sections, media)
- No publishing workflow (drafts, scheduling, SEO)
- Missing blog-specific features (excerpts, metadata, relationships)

## Feature Requirements

### Core Functionality

#### 1. Rich Content Editor
```html
<!-- Developer Implementation -->
<article class="insertr-content blog-post">
  <h1>Existing Title</h1>
  <p>Content with <strong class="brand-highlight">custom styling</strong></p>
  <blockquote class="testimonial">Styled quotes</blockquote>
</article>
```

**Capabilities:**
- Inline editing mode with contextual toolbar
- Style detection and preservation of developer CSS classes
- Block-based content management (headings, paragraphs, lists, quotes)
- Media insertion and management
- Markdown shortcuts for power users

#### 2. Content Structure Management
- Automatic heading hierarchy detection and validation
- Drag & drop block reordering
- Content outline/table of contents generation
- Block templates for common patterns
- Live content structure preview

#### 3. Enhanced Writing Experience
- Distraction-free full-screen mode
- Auto-save with conflict resolution
- Word count and reading time estimation
- Typography optimization for readability
- Smart formatting (quotes, dashes, spacing)

### Static Site Integration

#### 1. Enhanced File Processing
```bash
# Enhance existing pages
insertr enhance blog-post.html --output dist/blog-post.html

# Generate content-driven pages
insertr enhance templates/ --output dist/ --generate-content
```

#### 2. Template-Based Generation
```yaml
# insertr.yaml
content_types:
  blog_posts:
    template: "templates/blog-post.html"
    output_pattern: "blog/{slug}.html"
    fields:
      title: text
      content: insertr-content
      excerpt: text
      published_date: date
      author: text
```

#### 3. Content Storage Strategy
```go
type BlogPost struct {
    ID           string    `json:"id"`
    Slug         string    `json:"slug"`
    Title        string    `json:"title"`
    Content      string    `json:"content"`      // Rich HTML from .insertr-content
    Excerpt      string    `json:"excerpt"`
    Author       string    `json:"author"`
    PublishedAt  time.Time `json:"published_at"`
    Status       string    `json:"status"`       // draft, published, archived
    Template     string    `json:"template"`
    Metadata     JSON      `json:"metadata"`     // SEO, social media, etc.
}
```

### Blog Management Features

#### 1. Publishing Workflow
- Draft → Review → Published status management
- Content scheduling for future publication
- Version history with rollback capabilities
- Content approval workflow for teams

#### 2. SEO and Metadata
- Meta title and description management
- Open Graph and Twitter Card optimization
- Structured data (JSON-LD) generation
- Reading time and content analysis
- Heading structure validation

#### 3. Content Organization
- Categories and tags management
- Related content suggestions
- Content series/collections
- Author management and attribution

## Technical Architecture

### Frontend Components

#### 1. ContentEditor Class
```javascript
class ContentEditor extends StyleAwareEditor {
  constructor(element, options) {
    super(element, {
      mode: 'content',
      showOutline: true,
      enableMarkdownShortcuts: true,
      autoSave: true,
      ...options
    });
  }
  
  // Content-specific methods
  insertBlock(type) { /* Insert heading, quote, code block */ }
  reorderBlocks() { /* Drag & drop reordering */ }
  generateOutline() { /* TOC generation */ }
  validateStructure() { /* SEO and accessibility checks */ }
}
```

#### 2. Enhanced UI Components
- **Block Selector**: Visual insertion of headings, quotes, media
- **Outline Panel**: Collapsible content structure navigator
- **Style Panel**: Context-aware formatting options
- **Media Browser**: Integrated asset management
- **Metadata Editor**: SEO and social media optimization

#### 3. Content Structure Engine
```javascript
class ContentStructureEngine extends StyleDetectionEngine {
  analyzeContentBlocks(element) {
    // Detect semantic structure (headings, sections, articles)
    // Generate content outline and navigation
    // Identify reusable content patterns
  }
  
  validateContentStructure(structure) {
    // SEO heading hierarchy validation
    // Accessibility compliance checks
    // Content readability analysis
  }
}
```

### Backend Enhancements

#### 1. Content Generation Pipeline
```go
func (e *Enhancer) EnhanceWithContentGeneration(inputDir, outputDir string) error {
    // 1. Enhance existing HTML files (current behavior)
    err := e.EnhanceDirectory(inputDir, outputDir)
    if err != nil {
        return err
    }
    
    // 2. Generate content-driven pages
    return e.generateContentPages(outputDir)
}
```

#### 2. Template Processing
- Mustache/Handlebars template engine integration
- Content type-specific template routing
- Dynamic page generation from database content
- Static asset optimization and copying

#### 3. Content API Extensions
- Blog post CRUD operations
- Content publishing workflow endpoints
- SEO metadata management
- Media upload and optimization
- Version control and history tracking

## Implementation Phases

### Phase 1: Core Rich Text Editor (4-6 weeks)
**Deliverables:**
- Basic `.insertr-content` class recognition
- Inline editing with floating toolbar
- Style detection and preservation
- Auto-save functionality
- Block-based content management

**Success Criteria:**
- Edit long-form content in-place
- Preserve all existing CSS styling
- Support basic rich text formatting
- Maintain HTML structure integrity

### Phase 2: Content Structure & Management (4-6 weeks)
**Deliverables:**
- Content outline generation
- Drag & drop block reordering
- Media insertion and management
- Heading hierarchy validation
- SEO metadata editing

**Success Criteria:**
- Navigate content via outline
- Reorder content blocks visually
- Insert and manage images/media
- Validate content structure
- Edit meta descriptions and titles

### Phase 3: Static Site Integration (6-8 weeks)
**Deliverables:**
- Template-based page generation
- Content type configuration
- Publishing workflow
- Build process integration
- Documentation and examples

**Success Criteria:**
- Generate blog pages from templates
- Publish/unpublish content
- Integrate with existing build tools
- Complete documentation
- Demo implementations

### Phase 4: Advanced Features (6-8 weeks)
**Deliverables:**
- Collaborative editing
- Advanced SEO tools
- Content relationships
- Performance optimizations
- Third-party integrations

**Success Criteria:**
- Multiple editors simultaneously
- Comprehensive SEO analysis
- Related content suggestions
- Sub-second editor load times
- Hugo/Jekyll/Gatsby examples

## Potential Challenges & Mitigation Strategies

### Technical Challenges

#### 1. **Complex Content Structure Preservation**
**Challenge**: Maintaining perfect HTML fidelity while providing rich editing
**Mitigation**: 
- Extend existing HTMLPreservationEngine
- Comprehensive test suite for edge cases
- Gradual rollout with fallback mechanisms

#### 2. **Performance with Large Content**
**Challenge**: Editor performance degrades with very long articles
**Mitigation**:
- Virtual scrolling for large documents
- Lazy loading of editor features
- Incremental parsing and rendering
- Memory management optimizations

#### 3. **Style Detection Complexity**
**Challenge**: Complex CSS styling may not map well to editing interfaces
**Mitigation**:
- Configurable style mapping rules
- Developer override mechanisms
- Graceful degradation to basic formatting
- Comprehensive style detection testing

### User Experience Challenges

#### 4. **Editor Complexity vs Simplicity**
**Challenge**: Power users need advanced features, casual users need simplicity
**Mitigation**:
- Progressive disclosure of features
- Configurable interface complexity
- Role-based feature availability
- Contextual help and onboarding

#### 5. **Content Migration**
**Challenge**: Moving existing blog content into Insertr system
**Mitigation**:
- Import tools for common formats (Markdown, HTML, WordPress)
- Bulk migration utilities
- Content validation and cleanup tools
- Migration documentation and tutorials

### Integration Challenges

#### 6. **Static Site Generator Compatibility**
**Challenge**: Different SSGs have different content conventions
**Mitigation**:
- Plugin architecture for SSG-specific adaptations
- Standard export formats (Markdown, JSON, HTML)
- Configuration templates for popular SSGs
- Community-driven integration examples

#### 7. **Build Process Integration**
**Challenge**: Fitting into existing development workflows
**Mitigation**:
- CLI-first approach matching existing tools
- CI/CD pipeline integration guides
- Watch mode for development
- Incremental build optimizations

### Content Management Challenges

#### 8. **Version Control and Conflicts**
**Challenge**: Managing content changes across multiple editors and builds
**Mitigation**:
- Operational transformation for real-time collaboration
- Clear conflict resolution interfaces
- Audit trail for all content changes
- Backup and recovery mechanisms

#### 9. **SEO and Performance Balance**
**Challenge**: Rich editing features may impact site performance
**Mitigation**:
- Minimal runtime overhead for visitors
- Conditional loading of editing features
- Static generation maintains performance
- Performance monitoring and optimization

## Success Metrics

### User Adoption
- Number of sites using `.insertr-content`
- Content creation frequency
- User retention and engagement
- Community feedback and contributions

### Technical Performance
- Editor load time (target: <2 seconds)
- Content save latency (target: <500ms)
- Static site build impact (target: <10% increase)
- Memory usage optimization

### Content Quality
- Content structure validation pass rate
- SEO score improvements
- Accessibility compliance metrics
- User-reported content issues

## Open Questions & Decisions Needed

### Design Decisions
1. **Block vs. Inline Editing**: Should we prioritize block-based editing (like Gutenberg) or seamless inline editing?
2. **Markdown Support**: How much markdown compatibility should we maintain vs. pure HTML?
3. **Template Engine**: Which template engine should we standardize on for content generation?

### Technical Decisions
1. **Database Schema**: How should we structure content types and metadata in the database?
2. **API Design**: Should we extend existing APIs or create new content-specific endpoints?
3. **Caching Strategy**: How do we handle content caching across the editing and static generation pipeline?

### Integration Decisions
1. **SSG Priority**: Which static site generators should we prioritize for integration?
2. **Media Handling**: Should we build media management or integrate with existing solutions?
3. **Deployment**: How do we handle automated deployments when content is published?

## Next Steps

1. **Technical Spike** (1 week): Prototype core editing interface with existing StyleAwareEditor
2. **Design Review** (1 week): Validate UI/UX approach with user research
3. **Architecture Review** (1 week): Finalize technical architecture and database schema
4. **Phase 1 Kickoff**: Begin implementation of core rich text editor

## References

- [CLASSES.md](./CLASSES.md) - Current class system documentation
- [StyleAwareEditor](./lib/src/ui/style-aware-editor.js) - Existing editor implementation
- [HTMLPreservationEngine](./lib/src/utils/html-preservation.js) - Current preservation approach
- [Content Enhancement Pipeline](./internal/content/enhancer.go) - Static site processing

---

*This document is a living specification that will evolve as we learn more about user needs and technical constraints. All stakeholders should contribute to its refinement.*