igny8/plugins/wordpress/source/igny8-wp-bridge/templates/README.md

# IGNY8 Custom Content Template

## Overview

The IGNY8 WordPress Bridge plugin now includes a custom post template that automatically applies to IGNY8-generated content, providing a beautiful, magazine-style layout that mirrors the IGNY8 app's content view.

## Features

✅ **Automatic Detection** - Only activates for posts with `_igny8_content_id` meta field
✅ **Theme Compatible** - Inherits all theme colors and fonts
✅ **Responsive Design** - Works beautifully on all devices
✅ **Section-Based Layout** - Content parsed into introduction + H2 sections
✅ **Image Prompts** - Displays AI image generation prompts
✅ **SEO Metadata** - Shows meta title and description
✅ **Content Metadata** - Displays clusters, keywords, content type
✅ **Professional Typography** - Clean, readable prose styles

## How It Works

### Detection

The template automatically detects IGNY8-generated content by checking for the `_igny8_content_id` post meta field. If found, the custom template is loaded instead of the theme's default `single.php`.

### Template Structure

```
templates/
├── single-igny8-content.php          # Main template
├── parts/
│   ├── igny8-header.php              # Title, status, metadata
│   ├── igny8-featured-image.php      # Featured image with prompt
│   ├── igny8-content-sections.php    # Parsed content sections
│   └── igny8-metadata.php            # IGNY8 metadata footer
└── assets/
    ├── css/
    │   └── igny8-content-template.css # Styles
    └── js/
        └── igny8-content-template.js  # Optional enhancements
```

### Content Parsing

The template automatically parses your content HTML:

1. **Introduction** - All content before the first H2 heading
2. **Sections** - Each H2 creates a new section with:
   - Section number badge
   - Heading
   - Content
   - In-article image (if available)

### Image Display

- **Featured Image** - Displayed prominently with AI prompt
- **In-Article Images** - Positioned next to sections (side-by-side on desktop)
- **Image Prompts** - AI generation prompts shown below images

## Metadata Display

### Header Section
- Post title
- Status badge (Draft/Published/etc.)
- Posted date
- Word count
- Author
- Categories
- Tags
- SEO metadata (if different from post title)
- Content info (type, structure, cluster, keywords)

### Footer Section
- Collapsible IGNY8 metadata
- Content ID, Task ID
- Content type and structure
- Source
- Cluster and Sector IDs
- Secondary keywords
- Last sync time

## Theme Compatibility

The template is designed to work with ANY WordPress theme by:

### 1. Color Inheritance
```css
color: inherit;                    /* Uses theme's text color */
background: var(--wp--preset--color--base, #ffffff);  /* Uses theme's background */
```

### 2. Font Inheritance
```css
font-family: inherit;              /* Uses theme's font */
```

### 3. Minimal Overrides
Only structural styles are applied (spacing, borders, etc.)
Colors use opacity overlays: `rgba(0, 0, 0, 0.08)` for neutrals

### 4. CSS Custom Properties
Respects theme's CSS custom properties when available

## Customization

### Disable Template

To disable the custom template and use your theme's default:

```php
// Add to your theme's functions.php
add_filter('single_template', function($template) {
    // Remove IGNY8 template filter
    remove_filter('single_template', [Igny8_Template_Loader::class, 'load_igny8_template'], 99);
    return $template;
}, 98);
```

### Customize Styles

You can override styles by adding to your theme's CSS:

```css
/* Override max width */
.igny8-content-container {
    max-width: 1400px;
}

/* Customize section number badge */
.igny8-section-number {
    background: your-theme-color;
    color: white;
}
```

### Modify Template Parts

You can copy template parts to your theme and modify:

```
your-theme/
└── igny8-templates/
    └── parts/
        └── igny8-header.php  # Your custom header
```

Then filter the template part location:

```php
add_filter('igny8_template_part_path', function($path, $part) {
    $theme_path = get_stylesheet_directory() . '/igny8-templates/parts/' . $part . '.php';
    if (file_exists($theme_path)) {
        return $theme_path;
    }
    return $path;
}, 10, 2);
```

## Developer Reference

### Template Detection

```php
// Check if post is IGNY8 content
$template_loader = new Igny8_Template_Loader();
if ($template_loader->is_igny8_content($post_id)) {
    // This is IGNY8 content
}
```

### Helper Functions

```php
// Parse content into sections
$parsed = igny8_parse_content_sections($content_html);
// Returns: ['intro' => string, 'sections' => array]

// Get in-article images
$images = igny8_get_in_article_images($post_id);
// Returns: array indexed by position

// Get featured image prompt
$prompt = igny8_get_featured_image_prompt($post_id);
// Returns: string|null

// Calculate word count
$words = igny8_calculate_word_count($content);
// Returns: int

// Parse keywords
$keywords = igny8_parse_keywords($keywords_string);
// Returns: array
```

### Hooks & Filters

```php
// Modify template path
add_filter('igny8_template_path', function($path) {
    return $custom_path;
});

// Modify CSS enqueue
add_filter('igny8_template_css_url', function($url) {
    return $custom_url;
});

// Add custom body class
add_filter('body_class', function($classes) {
    if (is_igny8_content()) {
        $classes[] = 'my-custom-class';
    }
    return $classes;
});
```

## Troubleshooting

### Template Not Loading

1. **Check post meta**: Verify `_igny8_content_id` exists
   ```php
   $content_id = get_post_meta($post_id, '_igny8_content_id', true);
   var_dump($content_id); // Should not be empty
   ```

2. **Check file permissions**: Ensure template files are readable

3. **Clear cache**: Clear WordPress cache and browser cache

### Styles Not Applied

1. **Check enqueue**: Verify CSS is loading in page source
2. **Check theme conflicts**: Look for `!important` overrides in theme
3. **Check CSS specificity**: IGNY8 styles use minimal specificity

### Images Not Displaying

1. **Check meta field**: Verify `_igny8_imported_images` exists and is valid array
2. **Check attachment IDs**: Ensure image attachment IDs are valid
3. **Check image URLs**: Verify images are accessible

### Sections Not Parsing

1. **Check H2 tags**: Content must use `<h2>` for section headings
2. **Check HTML structure**: Ensure valid HTML
3. **Enable debug**: Add to wp-config.php:
   ```php
   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true);
   ```

## Performance

- **Minimal overhead**: Template only loads for IGNY8 content
- **CSS/JS loaded conditionally**: Assets only enqueued when needed
- **Efficient parsing**: DOMDocument used for reliable HTML parsing
- **No database queries**: All data from post meta (already cached)

## Browser Support

- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)
- Mobile browsers (iOS Safari, Chrome Mobile)

## Accessibility

- Semantic HTML5 elements
- Proper heading hierarchy
- Alt text for images
- Keyboard navigation support
- Print styles included

## License

GPL v2 or later - Same as WordPress

## Support

For issues or questions:
1. Check troubleshooting section above
2. Review implementation plan in `/docs/WP-CONTENT-TEMPLATE-IMPLEMENTATION-PLAN.md`
3. Check IGNY8 logs in WordPress admin

## Version History

### 1.0.0 (December 2025)
- Initial release
- Custom template for IGNY8 content
- Theme-compatible styling
- Section-based layout
- Image prompt display
- SEO metadata display