insertr/INITIAL.md

Insertr

A content management system for client websites.

I host a few client services and static web-sites and I want to integrate content management for the client. They should be able to change the content of the site, if not the layout. I am open to hearing about existing solutions, but I am considering building my own. If I were to build my own CMS I imagine an edit-in-place experience - probably with Go on the backend and something like htmx/alpine on the front-end, although I would be open for other alternatives.

Features / User stories

This list is not exhaustive and will be expanded as we research.

Users

This application have to keep three types of users in mind.

• The developer - Creating web-sites or services for small businisses
• The client - The one in daily control of the content. Sign in - make changes - see outcome. A simple system for any tech-litteracy level. "Update however and whenever you will, without involving tech support."
• The customer - Client's customers who will view and consume the site or service.

MVP

• Client should sign in through a SSO (I am hosting an authentik instance that should manage users through oAuth).
• See the public-facing version of their page, but with an edit button in the top right corner of "content components". If they click the button the content will be replaced with a form coresponding to the component's content, rendered in markdown. They can edit the content and submit/save their changes.
• This will trigger an update of the content on the server.

If I were to write a wish list it would be:

• Slapp a class on a div:
  |

  , and it works.

Research Results (Completed)

Existing Solutions Analysis

• TinaCMS: Git-based with visual editing, but requires Next.js/React framework
• Strapi: Full headless CMS, complex setup, Node.js based
• Contentful: Commercial solution, API-based, not self-hosted
• Ghost: Publishing-focused, not suitable for general content management
• Conclusion: No existing solution offers the simple "add a class and it works" approach

Tech Stack Decision: Go + htmx/Alpine

Rationale:

• Go: Fast, single binary deployment, excellent web server performance
• htmx: Perfect for edit-in-place with partial page updates
• Alpine.js: Lightweight reactive behaviors without framework complexity
• Architecture: Dynamic (not static site generation) for real-time editing

Authentication Integration

• Authentik OAuth 2.0: Standard flow for client authentication
• JWT tokens: For API authorization and session management
• Multi-tenant: Role-based access per site/content section

Prototype Roadmap

Phase 1: Frontend Proof-of-Concept

Goal: Demonstrate edit-in-place functionality with mock data Deliverables:

• Demo business website (Acme Consulting example)
• insertr.js library with core functionality
• Three user view modes (Customer/Client/Developer)
• Mock authentication flow
• Inline editing with markdown support

Phase 2: Backend Integration

Goal: Connect to Go server with real data persistence Deliverables:

• Go HTTP server with REST API
• File-based content storage
• Authentik OAuth integration
• Git-based version control

Phase 3: Production Features

Goal: Multi-tenant deployment ready system Deliverables:

• Admin dashboard
• Content validation and security
• Deployment automation
• Documentation and examples

User Experience Design

The Customer (End User)

• Clean website experience with no edit interface
• Fast loading, no unnecessary JavaScript

The Client (Content Manager)

• Same website + subtle edit indicators (✏️ icons)
• Click to edit → inline form → save/cancel
• Markdown editing for rich content
• Immediate visual feedback

The Developer (Integration)

<!-- Simple integration -->
<script src="https://insertr.example.com/insertr.js"></script>
<div class="insertr" data-content-id="hero">
  <h1>Editable Content</h1>
</div>

Next Immediate Steps

1. Create demo website mockup
2. Build core insertr.js library
3. Implement edit-in-place UI
4. Add mock authentication flow
5. Test with multiple content types