seo/AUTHOR_FILTER_GUIDE.md

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):

# 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:

# 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:

# 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:

./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:

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

./seo export --author admin

Output: output/all_posts_YYYY-MM-DD.csv

Example 2: Export Specific Author from Specific Site

./seo export --author "Marie" --site webscroll.fr

Example 3: Export Multiple Authors

./seo export --author "John" "Marie" "Admin"

Example 4: Export by Author ID

./seo export --author-id 5

Example 5: Combine Author and Site Filters

./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:

   ./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:

   curl -u username:password https://yoursite.com/wp-json/wp/v2/users
   

Tips

1. Use quotes for names with spaces:

   ./seo export --author "John Doe"  # ✓ Correct
   ./seo export --author John Doe    # ✗ Wrong (treated as 2 authors)
   

2. Partial matching is your friend:

   ./seo export --author "john"  # Matches "John Doe", "Johnny", etc.
   

3. Combine with migration:

   # 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:

   ./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:

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 - Post migration guide
• README.md - Main documentation