# Product Updates Automation Documentation

## Overview

The product updates system automatically generates and maintains discovery files (llms.txt, llms-full.txt) whenever product updates are created, edited, or deleted through the admin interface. Additionally, dynamic XML sitemaps and RSS feeds are generated on-demand. Individual feature post pages are automatically included in all discovery mechanisms. Main site URLs use v2/data/sitemap-pages.json and /sitemap.xml; sitemap.txt is no longer used.

## How It Works

### Automatic Regeneration

When content is saved via the admin interface (`produkt_updates_admin.php`), the `saveUpdatesData()` function automatically calls `regenerateDiscoveryFiles()`, which:

1. ~~Generates updated `html/sitemap.txt`~~ (deprecated; main site uses v2/data/sitemap-pages.json and /sitemap.xml; product updates use /sitemap-produkt-updates.xml on-demand)
2. Updates `html/llms.txt` with current month + last 2 months
3. Updates `html/llms-full.txt` with all months
4. Updates "Last Updated" dates in LLMS file headers

### Manual Regeneration

A "Regenerate Sitemap & LLMS" button is available in the admin header. Clicking it manually triggers regeneration without requiring any content changes.

## Files Generated

### ~~Sitemap.txt~~ (deprecated)

sitemap.txt is no longer used. Main site URLs are in **v2/data/sitemap-pages.json**; /sitemap.xml is generated from that. Product updates are in **/sitemap-produkt-updates.xml** (generated on-demand from produkt_updates.json). The "Regenerate Sitemap & LLMS" button still runs but no longer writes sitemap.txt.

### LLMS.txt (`html/llms.txt`)

- **Format**: Structured text with metadata
- **Content**: Current month + last 2 months only
- **Section**: Added after "Unternehmen" section, before "Kontakt & Support"
- **Format**:

  ```
  ## Produkt-Updates (Product Updates)

  > [UPDATES: Monat | Features] Produkt-Updates - Entdecke neueste Features...
  https://www.ordio.com/produkt-updates

  > [UPDATE: {Month} | {Count} Features] {Month} Updates - {Intro}...
  https://www.ordio.com/produkt-updates/{slug}
  ```

### LLMS-Full.txt (`html/llms-full.txt`)

- **Format**: Same as llms.txt
- **Content**: All months (no limit)
- **Section**: Same location as llms.txt

### XML Sitemap (`/sitemap-produkt-updates.xml`)

- **Format**: XML following sitemap.org protocol
- **Content**: Main page + all month pages + all post pages
- **Relationship to main sitemap**: The main sitemap (`/sitemap.xml`) reads from `v2/data/sitemap-pages.json` (main site URLs only). Produkt-updates URLs appear only in this sitemap. `robots.txt` references /sitemap.xml, /sitemap-blog.xml, and /sitemap-produkt-updates.xml (no sitemap.txt).
- **Metadata**:
  - Main page: priority 0.8, changefreq weekly
  - Month pages: priority 0.7, changefreq monthly
  - Post pages: priority 0.6, changefreq monthly
  - lastmod: Uses published_date or last_updated (whichever is newer)

### RSS Feed (`/produkt-updates/feed.xml`)

- **Format**: RSS 2.0
- **Content**: Last 12 months of updates + individual post items
- **Metadata**: Title, description, pubDate, guid per month and per post
- **Structure**: Month items followed by their individual post items

## Generator Scripts

### `v2/api/generate-sitemap.php`

**Function**: `generateSitemap()` (no-op)

- sitemap.txt is no longer used. This function returns success without writing any file so that `regenerateDiscoveryFiles()` in the admin can still call it. Main site: v2/data/sitemap-pages.json and /sitemap.xml. Product updates: /sitemap-produkt-updates.xml (on-demand).

**Returns**: Array with `success`, `message`, `urls_added` (urls_added always 0)

### `v2/api/generate-llms.php`

**Function**: `generateLLMS()`

- Reads existing llms.txt and llms-full.txt
- Reads produkt_updates.json
- Removes old product updates sections
- Adds new product updates sections
- Updates "Last Updated" dates

**Returns**: Array with `success`, `message`, `llms`, `llms_full`

**Helper Functions**:

- `processLLMSFile()` - Processes a single LLMS file
- `updateLLMSDate()` - Updates date in file header

## Dynamic Generators

### `v2/pages/sitemap-produkt-updates.xml.php`

- Generates XML sitemap on-demand
- Sets Content-Type: `application/xml`
- Accessible at: `/sitemap-produkt-updates.xml`

### `v2/pages/produkt-updates-feed.xml.php`

- Generates RSS feed on-demand
- Sets Content-Type: `application/rss+xml`
- Accessible at: `/produkt-updates/feed.xml`
- Limited to last 12 months

## URL Routing

### `.htaccess` Routes

```
RewriteRule ^produkt-updates\/feed\.xml$ v2/pages/produkt-updates-feed.xml.php [L]
RewriteRule ^sitemap-produkt-updates\.xml$ v2/pages/sitemap-produkt-updates.xml.php [L]
```

### `robots.txt` References

```
Sitemap: https://www.ordio.com/sitemap-produkt-updates.xml
```

## Schema Markup

### Main Page (`produkt_updates.php`)

- **Type**: `CollectionPage`
- **Fields**: datePublished, dateModified, numberOfItems, mainEntity (ItemList)
- **BreadcrumbList**: Home → Produkt-Updates

### Month Pages (`produkt_updates_month.php`)

- **Type**: `BlogPosting`
- **Fields**: headline, author, publisher, datePublished, dateModified, mainEntityOfPage, image (if available), keywords
- **BreadcrumbList**: Home → Produkt-Updates → {Month}

## Troubleshooting

### Sitemap Not Updating

1. ~~Check file permissions on `html/sitemap.txt`~~ (sitemap.txt no longer used)
2. Check error logs for generation errors
3. Verify `v2/api/generate-sitemap.php` exists and is readable
4. Try manual regeneration via admin button

### LLMS Files Not Updating

1. Check file permissions on `html/llms.txt` and `html/llms-full.txt`
2. Verify section markers exist ("## Kontakt & Support")
3. Check error logs
4. Try manual regeneration

### XML Sitemap Not Accessible

1. Verify `.htaccess` route exists
2. Check file permissions on `v2/pages/sitemap-produkt-updates.xml.php`
3. Test URL directly: `/sitemap-produkt-updates.xml`
4. Check Apache error logs

### RSS Feed Not Accessible

1. Verify `.htaccess` route exists
2. Check file permissions
3. Test URL directly: `/produkt-updates/feed.xml`
4. Validate RSS syntax with online validator

### Schema Validation Errors

1. Use Google Rich Results Test: https://search.google.com/test/rich-results
2. Check JSON-LD syntax (no trailing commas, proper escaping)
3. Verify all required fields present
4. Check for special characters in content

## Manual Regeneration

### Via Admin Interface

1. Log into `/produkt-updates-admin`
2. Click "Regenerate Sitemap & LLMS" button in header
3. Confirm dialog
4. Check result message

### Via Command Line

```bash
# Generate sitemap
php v2/api/generate-sitemap.php

# Generate LLMS files
php v2/api/generate-llms.php
```

### Via Direct URL (if needed)

```
/v2/api/generate-sitemap.php
/v2/api/generate-llms.php
```

Returns JSON with success status.

## Maintenance

### Regular Tasks

- **Monthly**: Verify sitemap includes all months
- **After major changes**: Test XML sitemap and RSS feed
- **Quarterly**: Validate schema markup with Google Rich Results Test

### Monitoring

- Check error logs for generation failures
- ~~Monitor sitemap.txt file size~~ (sitemap.txt no longer used)
- Verify LLMS files update dates change after saves

## Best Practices

1. **Always test after changes**: Save a test update and verify files regenerate
2. **Check file permissions**: Ensure web server can write to `html/` directory
3. **Validate outputs**: Use online validators for XML sitemap and RSS feed
4. **Monitor errors**: Check error logs regularly for generation failures
5. **Backup before major changes**: Backup LLMS files (and v2/data/sitemap-pages.json if editing main site URLs) before bulk updates

## Error Handling

- Generation errors are logged but don't break admin flow
- Failed generations log to PHP error_log
- Admin UI shows success/error messages after manual regeneration
- Automatic regeneration failures are silent (logged only)

## Security Considerations

- Generator scripts validate file paths
- Admin authentication required for manual regeneration
- File operations use safe paths (no directory traversal)
- All output is sanitized

## Performance

- Sitemap generation: < 100ms typically
- LLMS generation: < 200ms typically
- XML sitemap: Generated on-demand (cached by browser/CDN)
- RSS feed: Generated on-demand (cached by browser/CDN)

## Future Enhancements

- Consider caching generated files with TTL
- Add webhook support for external notifications
- Add sitemap index file if number of URLs exceeds 50,000
- Consider adding JSON-LD structured data to RSS feed items