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:
226
AUTHOR_FILTER_GUIDE.md
Normal file
226
AUTHOR_FILTER_GUIDE.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# Author Filter Guide
|
||||
|
||||
Export posts from specific authors using the enhanced export functionality.
|
||||
|
||||
## Overview
|
||||
|
||||
The export command now supports filtering posts by author name or author ID, making it easy to:
|
||||
- Export posts from a specific author across all sites
|
||||
- Combine author filtering with site filtering
|
||||
- Export posts from multiple authors at once
|
||||
|
||||
## Usage
|
||||
|
||||
### Filter by Author Name
|
||||
|
||||
Export posts from a specific author (case-insensitive, partial match):
|
||||
|
||||
```bash
|
||||
# Export posts by "John Doe"
|
||||
./seo export --author "John Doe"
|
||||
|
||||
# Export posts by "admin" (partial match)
|
||||
./seo export --author admin
|
||||
|
||||
# Export posts from multiple authors
|
||||
./seo export --author "John Doe" "Jane Smith"
|
||||
```
|
||||
|
||||
### Filter by Author ID
|
||||
|
||||
Export posts from specific author IDs:
|
||||
|
||||
```bash
|
||||
# Export posts by author ID 1
|
||||
./seo export --author-id 1
|
||||
|
||||
# Export posts from multiple author IDs
|
||||
./seo export --author-id 1 2 3
|
||||
```
|
||||
|
||||
### Combine with Site Filter
|
||||
|
||||
Export posts from a specific author on a specific site:
|
||||
|
||||
```bash
|
||||
# Export John's posts from mistergeek.net only
|
||||
./seo export --author "John Doe" --site mistergeek.net
|
||||
|
||||
# Export posts by author ID 1 from webscroll.fr
|
||||
./seo export --author-id 1 -s webscroll.fr
|
||||
```
|
||||
|
||||
### Dry Run Mode
|
||||
|
||||
Preview what would be exported:
|
||||
|
||||
```bash
|
||||
./seo export --author "John Doe" --dry-run
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Author Name Matching**
|
||||
- Case-insensitive matching
|
||||
- Partial matches work (e.g., "john" matches "John Doe")
|
||||
- Matches against author's display name and slug
|
||||
|
||||
2. **Author ID Matching**
|
||||
- Exact match on WordPress user ID
|
||||
- More reliable than name matching
|
||||
- Useful when authors have similar names
|
||||
|
||||
3. **Author Information**
|
||||
- The exporter fetches all authors from each site
|
||||
- Author names are included in the exported CSV
|
||||
- Posts are filtered before export
|
||||
|
||||
## Export Output
|
||||
|
||||
The exported CSV includes author information:
|
||||
|
||||
```csv
|
||||
site,post_id,status,title,slug,url,author_id,author_name,date_published,...
|
||||
mistergeek.net,123,publish,"VPN Guide",vpn-guide,https://...,1,John Doe,2024-01-15,...
|
||||
```
|
||||
|
||||
### New Column: `author_name`
|
||||
|
||||
The export now includes the author's display name in addition to the author ID.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Export All Posts by Admin
|
||||
|
||||
```bash
|
||||
./seo export --author admin
|
||||
```
|
||||
|
||||
Output: `output/all_posts_YYYY-MM-DD.csv`
|
||||
|
||||
### Example 2: Export Specific Author from Specific Site
|
||||
|
||||
```bash
|
||||
./seo export --author "Marie" --site webscroll.fr
|
||||
```
|
||||
|
||||
### Example 3: Export Multiple Authors
|
||||
|
||||
```bash
|
||||
./seo export --author "John" "Marie" "Admin"
|
||||
```
|
||||
|
||||
### Example 4: Export by Author ID
|
||||
|
||||
```bash
|
||||
./seo export --author-id 5
|
||||
```
|
||||
|
||||
### Example 5: Combine Author and Site Filters
|
||||
|
||||
```bash
|
||||
./seo export --author "John" --site mistergeek.net --verbose
|
||||
```
|
||||
|
||||
## Finding Author IDs
|
||||
|
||||
If you don't know the author ID, you can:
|
||||
|
||||
1. **Export all posts and check the CSV:**
|
||||
```bash
|
||||
./seo export
|
||||
# Then open the CSV and check the author_id column
|
||||
```
|
||||
|
||||
2. **Use WordPress Admin:**
|
||||
- Go to Users → All Users
|
||||
- Hover over a user name
|
||||
- The URL shows the user ID (e.g., `user_id=5`)
|
||||
|
||||
3. **Use WordPress REST API directly:**
|
||||
```bash
|
||||
curl -u username:password https://yoursite.com/wp-json/wp/v2/users
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Use quotes for names with spaces:**
|
||||
```bash
|
||||
./seo export --author "John Doe" # ✓ Correct
|
||||
./seo export --author John Doe # ✗ Wrong (treated as 2 authors)
|
||||
```
|
||||
|
||||
2. **Partial matching is your friend:**
|
||||
```bash
|
||||
./seo export --author "john" # Matches "John Doe", "Johnny", etc.
|
||||
```
|
||||
|
||||
3. **Combine with migration:**
|
||||
```bash
|
||||
# Export author's posts, then migrate to another site
|
||||
./seo export --author "John Doe" --site webscroll.fr
|
||||
./seo migrate output/all_posts_*.csv --destination mistergeek.net
|
||||
```
|
||||
|
||||
4. **Verbose mode for debugging:**
|
||||
```bash
|
||||
./seo export --author "John" --verbose
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No posts exported
|
||||
|
||||
**Possible causes:**
|
||||
- Author name doesn't match (try different spelling)
|
||||
- Author has no posts
|
||||
- Author doesn't exist on that site
|
||||
|
||||
**Solutions:**
|
||||
- Use `--verbose` to see what's happening
|
||||
- Try author ID instead of name
|
||||
- Check if author exists on the site
|
||||
|
||||
### Author names not showing in CSV
|
||||
|
||||
**Possible causes:**
|
||||
- WordPress REST API doesn't allow user enumeration
|
||||
- Authentication issue
|
||||
|
||||
**Solutions:**
|
||||
- Check WordPress user permissions
|
||||
- Verify credentials in config
|
||||
- Author ID will still be present even if name lookup fails
|
||||
|
||||
## API Usage
|
||||
|
||||
Use author filtering programmatically:
|
||||
|
||||
```python
|
||||
from seo.app import SEOApp
|
||||
|
||||
app = SEOApp()
|
||||
|
||||
# Export by author name
|
||||
csv_file = app.export(author_filter=["John Doe"])
|
||||
|
||||
# Export by author ID
|
||||
csv_file = app.export(author_ids=[1, 2])
|
||||
|
||||
# Export by author and site
|
||||
csv_file = app.export(
|
||||
author_filter=["John"],
|
||||
site_filter="mistergeek.net"
|
||||
)
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `seo migrate` - Migrate exported posts to another site
|
||||
- `seo analyze` - Analyze exported posts with AI
|
||||
- `seo export --help` - Show all export options
|
||||
|
||||
## See Also
|
||||
|
||||
- [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) - Post migration guide
|
||||
- [README.md](README.md) - Main documentation
|
||||
Reference in New Issue
Block a user