saltcat-astro-editorial-imagesys

Editorial image management system for Astro websites, enabling easy in-context image editing and AI-powered generation.

Status

🚧 In Development - Phase 2 Complete (Core Vite Plugin Implementation)

Completed Features

• ✅ Phase 1: Foundation and Core Architecture
• ✅ Phase 2: Core Vite Plugin Implementation (Image detection, resolution, transformation)

Next Steps

• 🔨 Phase 3: Component Library
• 🔨 Phase 4: Development Mode Features (AI generation, external editor)
• 📝 Testing: Unit and integration tests

Overview

saltcat-astro-editorial-imagesys provides a pragmatic solution for managing editorial images in Astro-based articles and content. It allows content creators to define article-scoped images using special Markdown, MDX, Astro, or Svelte component syntax, with integrated support for AI image generation and external editing during development.

Key Features

• Article-scoped image management: Images are organized by article ID with automatic versioning
• Flexible syntax support: Works with Markdown, MDX, Astro, and Svelte components
• Automatic versioning: Uses numbered filenames (e.g., 0001_TAG.jpg) with automatic selection of highest version
• AI image generation: Development-mode "generate" button uses durable-imagegen CLI for AI-powered image creation
• External editor integration: Development-mode "edit" button launches user-specified image editor
• Vite plugin architecture: Seamless integration with Astro's build pipeline

Installation

npm install saltcat-astro-editorial-imagesys

Usage

Basic Configuration

Configure the Vite plugin in your Astro project:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import editorialImages from 'saltcat-astro-editorial-imagesys';

export default defineConfig({
  vite: {
    plugins: [
      editorialImages({
        // Optional: specify external editor command
        editor: 'gimp',
        // Optional: custom image directory
        imageDir: 'src/editorial-images'
      })
    ]
  }
});

Defining Editorial Images

Use special syntax in your content files to define editorial images:

Markdown/MDX:

![AI-generated landscape with mountains at sunset](editorial:landscape)

Astro Component:

---
import EditorialImage from 'saltcat-astro-editorial-imagesys/components/EditorialImage.astro';
---
<EditorialImage alt="AI-generated landscape with mountains at sunset" id="landscape" />

Svelte Component:

<script>
  import EditorialImage from 'saltcat-astro-editorial-imagesys/components/EditorialImage.svelte';
</script>

<EditorialImage alt="AI-generated landscape with mountains at sunset" id="landscape" />

Image Organization

Images are automatically organized by article:

src/editorial-images/
  └── my-blog-post/
      ├── landscape/
      │   ├── 0001_initial.jpg
      │   ├── 0002_revised.jpg
      │   └── 0003_final.jpg    ← This version will be displayed
      └── portrait/
          └── 0001_draft.jpg

The system automatically displays the highest-numbered image file. The tag portion after the underscore (e.g., _final) is informational only and ignored for version ordering.

Development Mode Features

AI Image Generation

When running in development mode, each editorial image displays a "Generate" button:

1. Click "Generate" on any editorial image placeholder
2. The system uses the image's ALT text as the AI prompt
3. durable-imagegen CLI generates the image
4. New image is automatically saved with incremented version number

External Editor Integration

Development mode also provides an "Edit" button for each image:

1. Click "Edit" on any editorial image
2. Your configured external editor opens with the current image
3. Save changes in your editor
4. System automatically creates new versioned copy

Architecture

Vite Plugin

The core Vite plugin:

• Detects editorial image syntax during build
• Creates directory structure in src/editorial-images/ARTICLE_ID/filename/
• Generates blank placeholder images when none exist
• Resolves highest-numbered version for display
• Injects development UI controls in dev mode

Image Versioning

Version numbers follow the pattern: NNNN_TAG.ext where:

• NNNN: Four-digit version number (0001, 0002, etc.)
• TAG: Optional descriptive tag (ignored for sorting)
• .ext: Image file extension

AI Integration

The system integrates with durable-imagegen CLI:

durable-imagegen "your alt text prompt" --output src/editorial-images/article-id/image-name/0001_generated.jpg

Configuration Options

Plugin Options

interface EditorialImagesConfig {
  // External image editor command
  editor?: string;

  // Base directory for editorial images
  imageDir?: string;

  // Enable/disable AI generation
  enableGeneration?: boolean;

  // Custom durable-imagegen CLI path
  imagegenPath?: string;
}

Environment Variables

• EDITORIAL_IMAGES_DIR: Override default image directory
• EDITORIAL_IMAGES_EDITOR: Override default editor command
• DURABLE_IMAGEGEN_PATH: Custom path to durable-imagegen CLI

Development

Setup

npm install
npm run build
npm test

Project Structure

saltcat-astro-editorial-imagesys/
├── src/
│   ├── plugin/           # Vite plugin implementation
│   ├── components/       # Astro & Svelte components
│   ├── utils/           # Image versioning and file utilities
│   └── cli/             # CLI integration
├── test/                # Comprehensive test suite
└── README.md

Philosophy

This system embodies Durable Programming's core principles:

Pragmatic Problem-Solving

Solves the real-world challenge of managing editorial images in content-heavy Astro sites without requiring complex DAM systems or workflows.

Sustainability and Longevity

• Simple file-based architecture that doesn't depend on external services
• Version history preserved through numbered files
• Works with standard image formats and existing tools

Modular and Composable Design

• Vite plugin architecture integrates cleanly with Astro
• Components work across multiple syntaxes (MDX, Astro, Svelte)
• External editor integration respects user preferences

Developer Experience

• Intuitive syntax matching existing image usage patterns
• Development UI eliminates context switching
• ALT text doubles as AI prompt for efficient workflow

Incremental Improvement

• Version numbering supports iterative image refinement
• Preserves image history for rollback
• Non-destructive editing workflow

Requirements

• Node.js 18+
• Astro 3.0+
• durable-imagegen CLI (for AI generation features)

License

MIT

Support

For issues, questions, or contributions, visit the project repository or contact [email protected].

Part of the Saltcat design system ecosystem.