# Blog Post Date Management Guide

**Last Updated:** 2026-01-12

Complete guide for managing "last updated" dates for blog posts, including when to update dates, how dates are used in meta tags and schema.org, and maintenance procedures.

## Overview

Blog posts have two important dates:

- **`publication_date`**: The original publication date (never changes)
- **`modified_date`**: The last significant content update date (updates when content changes)

Both dates are stored in ISO 8601 format (`YYYY-MM-DDTHH:MM:SS+00:00`) in the blog post JSON files.

## Date Usage

### Meta Tags

The `modified_date` is used in the `article:modified_time` meta tag:

```html
<meta property="article:modified_time" content="2026-01-10T18:01:59+00:00" />
```

### Schema.org Markup

The `modified_date` is used in schema.org `dateModified` fields for both `Article` and `WebPage` schemas:

```json
{
  "@type": "Article",
  "datePublished": "2023-09-01T10:40:44+00:00",
  "dateModified": "2026-01-10T18:01:59+00:00"
}
```

### UI Display

The "last updated" date is displayed conditionally:

- **PostHeader component**: Shows updated date if it's 7+ days after publication date
- **PostCard component**: Shows updated date if it's 7+ days after publication date (default variant only)

Format: "Zuletzt aktualisiert: 10. Januar 2026"

## When to Update `modified_date`

### ✅ Update When:

- Post content HTML is modified significantly
- Title is changed (not just capitalization)
- Excerpt is rewritten
- Meta description is updated
- Featured image is changed
- Content structure changes (new sections, major rewrites)

### ❌ Do NOT Update When:

- Related posts are added/removed
- Internal links are updated
- Topics/clusters are reassigned
- Reading time is recalculated
- Minor formatting changes (spacing, punctuation)
- Metadata-only changes (author, category)

## Date Format Standards

### Required Format

- **ISO 8601**: `YYYY-MM-DDTHH:MM:SS+00:00`
- **Timezone**: Always UTC (`+00:00`)
- **No microseconds**: Remove `.123456` if present
- **String type**: Store as string in JSON, not number

### Examples

✅ **Correct:**

```json
{
  "publication_date": "2023-09-01T10:40:44+00:00",
  "modified_date": "2026-01-10T18:01:59+00:00"
}
```

❌ **Incorrect:**

```json
{
  "modified_date": "2026-01-10T18:01:59.391340" // Has microseconds
}
```

## Maintenance Scripts

### Audit Dates

Check all blog post dates for issues:

```bash
php v2/scripts/blog/audit-post-dates.php [--verbose] [--fix]
```

**What it checks:**

- Missing `modified_date` fields
- Invalid date formats
- Dates where `modified_date` < `publication_date`
- Date mismatches with file modification time

### Fix Date Formats

Normalize date formats across all posts:

```bash
php v2/scripts/blog/fix-post-dates.php [--dry-run] [--verbose]
```

**What it fixes:**

- Removes microseconds from dates
- Ensures UTC timezone
- Sets missing `modified_date` to file modification time
- Ensures `modified_date` >= `publication_date`

### Sync Dates from File Modification Time

Update `modified_date` based on file modification time:

```bash
php v2/scripts/blog/sync-dates-from-filemtime.php [--dry-run] [--force] [--verbose]
```

**When to use:**

- After bulk content updates
- When dates seem out of sync with file changes
- Use `--force` to update all dates regardless of difference

### Validate Dates

Validate all dates meet requirements:

```bash
php v2/scripts/blog/validate-post-dates.php [--verbose]
```

**What it validates:**

- All posts have `modified_date` set
- All dates are valid ISO 8601 format
- `modified_date` >= `publication_date`

### Detect Content Changes

Detect when content has changed and needs date update:

```bash
php v2/scripts/blog/detect-content-changes.php [--update] [--verbose]
```

**What it does:**

- Compares content hash with stored hash
- Identifies posts with significant content changes
- Optionally updates `modified_date` for changed posts

### Test Implementation

Test that dates are correctly implemented:

```bash
php v2/scripts/blog/test-date-implementation.php [--post=slug] [--category=category]
```

**What it tests:**

- JSON files have valid `modified_date`
- Meta tags use correct dates
- Schema.org uses correct dates
- Helper functions work correctly

## Workflow

### Regular Maintenance

**Weekly:**

```bash
# Validate all dates
php v2/scripts/blog/validate-post-dates.php

# Detect content changes
php v2/scripts/blog/detect-content-changes.php --update
```

**Monthly:**

```bash
# Full audit
php v2/scripts/blog/audit-post-dates.php --verbose

# Sync dates if needed
php v2/scripts/blog/sync-dates-from-filemtime.php --dry-run
```

### After Content Updates

When updating blog post content:

1. **Make content changes** to JSON file
2. **Run detection script:**
   ```bash
   php v2/scripts/blog/detect-content-changes.php --update
   ```
3. **Verify dates:**
   ```bash
   php v2/scripts/blog/test-date-implementation.php --post=your-slug
   ```

### After Bulk Operations

After bulk content migrations or updates:

1. **Fix date formats:**
   ```bash
   php v2/scripts/blog/fix-post-dates.php
   ```
2. **Sync with file modification times:**
   ```bash
   php v2/scripts/blog/sync-dates-from-filemtime.php --force
   ```
3. **Validate everything:**
   ```bash
   php v2/scripts/blog/validate-post-dates.php
   php v2/scripts/blog/test-date-implementation.php
   ```

## Best Practices

### SEO Best Practices

1. **Always include `dateModified`** in schema.org markup
2. **Always include `article:modified_time`** in meta tags
3. **Ensure `dateModified` >= `datePublished`**
4. **Update dates when content is significantly revised**
5. **Don't update dates for minor changes** (maintains trust)

### Content Editor Guidelines

1. **When editing content**: Dates update automatically via detection script
2. **When making minor fixes**: Don't manually update dates
3. **When making major updates**: Run detection script to update dates
4. **Check dates before publishing**: Use validation script

### Developer Guidelines

1. **Always validate dates** before committing changes
2. **Use scripts** instead of manual date updates
3. **Test implementation** after date changes
4. **Document date changes** in commit messages

## Troubleshooting

### Dates Not Showing in UI

**Issue**: Updated date not visible on post page

**Check:**

- Is `modified_date` 7+ days after `publication_date`?
- Is `modified_date` set correctly in JSON?
- Are helper functions loaded?

**Fix:**

```bash
php v2/scripts/blog/test-date-implementation.php --post=your-slug
```

### Invalid Date Format Errors

**Issue**: Date format validation errors

**Fix:**

```bash
php v2/scripts/blog/fix-post-dates.php
```

### Dates Out of Sync

**Issue**: Dates don't match file modification times

**Fix:**

```bash
php v2/scripts/blog/sync-dates-from-filemtime.php --force
```

### Schema Validation Errors

**Issue**: Google Rich Results Test shows date errors

**Check:**

- Dates are valid ISO 8601 format
- `dateModified` >= `datePublished`
- Dates are in UTC timezone

**Fix:**

```bash
php v2/scripts/blog/fix-post-dates.php
php v2/scripts/blog/validate-post-dates.php
```

## Related Documentation

- [Blog Template Development Guide](TEMPLATE_DEVELOPMENT_GUIDE.md) - Template structure and components
- [Blog Data Structure Mapping](DATA_STRUCTURE_MAPPING.md) - JSON schema definitions
- [Blog Template Best Practices](BLOG_TEMPLATE_BEST_PRACTICES.md) - Best practices guide

## Script Reference

All scripts are located in `v2/scripts/blog/`:

- `audit-post-dates.php` - Audit all dates
- `fix-post-dates.php` - Fix date formats
- `sync-dates-from-filemtime.php` - Sync dates from file mtime
- `validate-post-dates.php` - Validate dates
- `detect-content-changes.php` - Detect content changes
- `test-date-implementation.php` - Test implementation