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

<!-- 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

# 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

# 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

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

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

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

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 - Current class system documentation
• StyleAwareEditor - Existing editor implementation
• HTMLPreservationEngine - Current preservation approach
• Content Enhancement Pipeline - 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.