Add post migration and author filter features
- Add migrate command to transfer posts between websites - Support CSV-based and filtered migration modes - Preserve original post dates (with --ignore-original-date option) - Auto-create categories and tags on destination site - Add author filtering to export (--author and --author-id flags) - Include author_name column in exported CSV - Add comprehensive documentation (MIGRATION_GUIDE.md, AUTHOR_FILTER_GUIDE.md) Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
Kevin Bataille
269
MIGRATION_GUIDE.md
Normal file
269
MIGRATION_GUIDE.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# Post Migration Guide
|
||||
|
||||
This guide explains how to migrate posts between WordPress sites using the SEO automation tool.
|
||||
|
||||
## Overview
|
||||
|
||||
The migration feature allows you to move posts from one WordPress site to another while preserving:
|
||||
- Post content (title, body, excerpt)
|
||||
- Categories (automatically created if they don't exist)
|
||||
- Tags (automatically created if they don't exist)
|
||||
- SEO metadata (RankMath, Yoast SEO)
|
||||
- Post slug
|
||||
|
||||
## Migration Modes
|
||||
|
||||
There are two ways to migrate posts:
|
||||
|
||||
### 1. CSV-Based Migration
|
||||
|
||||
Migrate specific posts listed in a CSV file.
|
||||
|
||||
**Requirements:**
|
||||
- CSV file with at least two columns: `site` and `post_id`
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Basic migration (posts deleted from source after migration)
|
||||
./seo migrate posts_to_migrate.csv --destination mistergeek.net
|
||||
|
||||
# Keep posts on source site
|
||||
./seo migrate posts_to_migrate.csv --destination mistergeek.net --keep-source
|
||||
|
||||
# Publish immediately instead of draft
|
||||
./seo migrate posts_to_migrate.csv --destination mistergeek.net --post-status publish
|
||||
|
||||
# Custom output file for migration report
|
||||
./seo migrate posts_to_migrate.csv --destination mistergeek.net --output custom_report.csv
|
||||
```
|
||||
|
||||
### 2. Filtered Migration
|
||||
|
||||
Migrate posts based on filters (category, date, etc.).
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Migrate all posts from source to destination
|
||||
./seo migrate --source webscroll.fr --destination mistergeek.net
|
||||
|
||||
# Migrate posts from specific categories
|
||||
./seo migrate --source webscroll.fr --destination mistergeek.net --category-filter VPN "Torrent Clients"
|
||||
|
||||
# Migrate posts with specific tags
|
||||
./seo migrate --source webscroll.fr --destination mistergeek.net --tag-filter "guide" "tutorial"
|
||||
|
||||
# Migrate posts by date range
|
||||
./seo migrate --source webscroll.fr --destination mistergeek.net --date-after 2024-01-01 --date-before 2024-12-31
|
||||
|
||||
# Limit number of posts
|
||||
./seo migrate --source webscroll.fr --destination mistergeek.net --limit 10
|
||||
|
||||
# Combine filters
|
||||
./seo migrate --source webscroll.fr --destination mistergeek.net \
|
||||
--category-filter VPN \
|
||||
--date-after 2024-01-01 \
|
||||
--limit 5 \
|
||||
--keep-source
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
### Required Options
|
||||
|
||||
- `--destination`, `--to`: Destination site (mistergeek.net, webscroll.fr, hellogeek.net)
|
||||
- `--source`, `--from`: Source site (for filtered migration only)
|
||||
- CSV file: Path to CSV with posts (for CSV-based migration)
|
||||
|
||||
### Optional Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--keep-source` | Keep posts on source site after migration | Delete after migration |
|
||||
| `--post-status` | Status for migrated posts (draft, publish, pending) | draft |
|
||||
| `--no-categories` | Don't create categories automatically | Create categories |
|
||||
| `--no-tags` | Don't create tags automatically | Create tags |
|
||||
| `--category-filter` | Filter by category names (filtered migration) | All categories |
|
||||
| `--tag-filter` | Filter by tag names (filtered migration) | All tags |
|
||||
| `--date-after` | Migrate posts after this date (YYYY-MM-DD) | No limit |
|
||||
| `--date-before` | Migrate posts before this date (YYYY-MM-DD) | No limit |
|
||||
| `--limit` | Maximum number of posts to migrate | No limit |
|
||||
| `--output`, `-o` | Custom output file for migration report | Auto-generated |
|
||||
| `--dry-run` | Preview what would be done without doing it | Execute |
|
||||
| `--verbose`, `-v` | Enable verbose logging | Normal logging |
|
||||
|
||||
## Migration Process
|
||||
|
||||
### What Gets Migrated
|
||||
|
||||
1. **Post Content**
|
||||
- Title
|
||||
- Body content (HTML preserved)
|
||||
- Excerpt
|
||||
- Slug
|
||||
|
||||
2. **Categories**
|
||||
- Mapped from source to destination
|
||||
- Created automatically if they don't exist on destination
|
||||
- Hierarchical structure preserved (parent-child relationships)
|
||||
|
||||
3. **Tags**
|
||||
- Mapped from source to destination
|
||||
- Created automatically if they don't exist on destination
|
||||
|
||||
4. **SEO Metadata**
|
||||
- RankMath title and description
|
||||
- Yoast SEO title and description
|
||||
- Focus keywords
|
||||
|
||||
### What Doesn't Get Migrated
|
||||
|
||||
- Featured images (must be re-uploaded manually)
|
||||
- Post author (uses destination site's default)
|
||||
- Comments (not transferred)
|
||||
- Custom fields (except SEO metadata)
|
||||
- Post revisions
|
||||
|
||||
## Migration Report
|
||||
|
||||
After migration, a CSV report is generated in `output/` with the following information:
|
||||
|
||||
```csv
|
||||
source_site,source_post_id,destination_site,destination_post_id,title,status,categories_migrated,tags_migrated,deleted_from_source
|
||||
webscroll.fr,123,mistergeek.net,456,"VPN Guide",draft,3,5,True
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Migrate Specific Posts from CSV
|
||||
|
||||
1. Create a CSV file with posts to migrate:
|
||||
```csv
|
||||
site,post_id,title
|
||||
webscroll.fr,123,VPN Guide
|
||||
webscroll.fr,456,Torrent Tutorial
|
||||
```
|
||||
|
||||
2. Run migration:
|
||||
```bash
|
||||
./seo migrate my_posts.csv --destination mistergeek.net
|
||||
```
|
||||
|
||||
### Example 2: Migrate All VPN Content
|
||||
|
||||
```bash
|
||||
./seo migrate --source webscroll.fr --destination mistergeek.net \
|
||||
--category-filter VPN "VPN Reviews" \
|
||||
--post-status draft \
|
||||
--keep-source
|
||||
```
|
||||
|
||||
### Example 3: Migrate Recent Content
|
||||
|
||||
```bash
|
||||
./seo migrate --source webscroll.fr --destination mistergeek.net \
|
||||
--date-after 2024-06-01 \
|
||||
--limit 20
|
||||
```
|
||||
|
||||
### Example 4: Preview Migration
|
||||
|
||||
```bash
|
||||
./seo migrate --source webscroll.fr --destination mistergeek.net \
|
||||
--category-filter VPN \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Migration
|
||||
|
||||
1. **Backup both sites** - Always backup before bulk operations
|
||||
2. **Test with a few posts** - Migrate 1-2 posts first to verify
|
||||
3. **Check category structure** - Review destination site's categories
|
||||
4. **Plan URL redirects** - If deleting from source, set up redirects
|
||||
|
||||
### During Migration
|
||||
|
||||
1. **Use dry-run first** - Preview what will be migrated
|
||||
2. **Start with drafts** - Review before publishing
|
||||
3. **Monitor logs** - Watch for errors or warnings
|
||||
4. **Limit batch size** - Migrate in batches of 10-20 posts
|
||||
|
||||
### After Migration
|
||||
|
||||
1. **Review migrated posts** - Check formatting and categories
|
||||
2. **Add featured images** - Manually upload if needed
|
||||
3. **Set up redirects** - From old URLs to new URLs
|
||||
4. **Update internal links** - Fix cross-site links
|
||||
5. **Monitor SEO** - Track rankings after migration
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**1. "Site not found" error**
|
||||
- Check site name is correct (mistergeek.net, webscroll.fr, hellogeek.net)
|
||||
- Verify credentials in config.yaml or .env
|
||||
|
||||
**2. "Category already exists" warning**
|
||||
- This is normal - the migrator found a matching category
|
||||
- The existing category will be used
|
||||
|
||||
**3. "Failed to create post" error**
|
||||
- Check WordPress REST API is enabled
|
||||
- Verify user has post creation permissions
|
||||
- Check authentication credentials
|
||||
|
||||
**4. Posts missing featured images**
|
||||
- Featured images are not migrated automatically
|
||||
- Upload images manually to destination site
|
||||
- Update featured image on migrated posts
|
||||
|
||||
**5. Categories not matching**
|
||||
- Categories are matched by name (case-insensitive)
|
||||
- "VPN" and "vpn" will match
|
||||
- "VPN Guide" and "VPN" will NOT match - new category created
|
||||
|
||||
## API Usage
|
||||
|
||||
You can also use the migration feature programmatically:
|
||||
|
||||
```python
|
||||
from seo.app import SEOApp
|
||||
|
||||
app = SEOApp()
|
||||
|
||||
# CSV-based migration
|
||||
app.migrate(
|
||||
csv_file='output/posts_to_migrate.csv',
|
||||
destination_site='mistergeek.net',
|
||||
create_categories=True,
|
||||
create_tags=True,
|
||||
delete_after=False,
|
||||
status='draft'
|
||||
)
|
||||
|
||||
# Filtered migration
|
||||
app.migrate_by_filter(
|
||||
source_site='webscroll.fr',
|
||||
destination_site='mistergeek.net',
|
||||
category_filter=['VPN', 'Software'],
|
||||
date_after='2024-01-01',
|
||||
limit=10,
|
||||
create_categories=True,
|
||||
delete_after=False,
|
||||
status='draft'
|
||||
)
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `seo export` - Export posts from all sites
|
||||
- `seo editorial_strategy` - Analyze and get migration recommendations
|
||||
- `seo category_propose` - Get AI category recommendations
|
||||
|
||||
## See Also
|
||||
|
||||
- [README.md](README.md) - Main documentation
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture
|
||||
- [CATEGORY_MANAGEMENT_GUIDE.md](CATEGORY_MANAGEMENT_GUIDE.md) - Category management
|
||||
Reference in New Issue
Block a user