Kirby Instagram Importer

Import Instagram posts from Instaloader exports to KirbyCMS format.

Mission

Take ownership of your content and use your personal website as the hub for content syndication.

This tool helps you to group and convert your Instagram content to post.txt pages and gives you a head start in transitioning from publishing on Instagram to publishing from your own personal KirbyCMS website instead.

Requirements

• PHP 8.1+
• Instaloader for Instagram exports
• KirbyCMS 3.9+ or 4.0+ or 5.0+ (optional, for CLI command)

Installation

Option A: With KirbyCMS

cd /path/to/kirby-site
composer require emiland/kirby-instagram-importer

The plugin automatically installs the CLI command. Run:

kirby import:instagram --dry-run  # Preview changes
kirby import:instagram --backup   # Import with backup
kirby import:instagram            # Import directly

Option B: Standalone (without Kirby)

composer require emiland/kirby-instagram-importer

Run the import script:

composer run import                 # Import directly
composer run import-dry            # Preview changes
composer run import -- --backup    # Import with backup

Usage

Prepare Your Instagram Export

1. Install Instaloader
2. Export your Instagram data:

   instaloader --login=yourusername --dirname-pattern={profile}
   

   Or for specific profile:

   instaloader profile:yourusername
   

3. The script expects Instaloader's filename format: YYYY-MM-DD_HH-MM-SS_UTC_N.ext

Run Import

kirby import:instagram <source_dir> [output_dir]

Arguments:

• source_dir (required) - Directory containing Instaloader exports
• output_dir (optional) - Output directory for feed content (default: auto-detect)

Examples:

# Import from specific directory (output auto-detected)
kirby import:instagram /path/to/instaloader-export

# Import with custom output directory
kirby import:instagram /path/to/export /path/to/kirby/content/feed

# Preview changes
kirby import:instagram /path/to/export --dry-run

# Import with backup
kirby import:instagram /path/to/export --backup

Options

Option	Description
--dry-run	Preview changes without modifying files
--backup	Create timestamped backup of source files before import

Output Structure

The importer auto-detects your project structure:

Within a KirbyCMS project (if /content folder exists):

/content/feed/
└── {year}/
    └── {monthName}-{day}/
        ├── post.txt          # Kirby content file
        └── {media files}    # Copied images/videos

Standalone (no /content folder detected):

./feed/
└── {year}/
    └── {monthName}-{day}/
        ├── post.txt
        └── {media files}

Custom output directory:

kirby import:instagram /path/to/export /custom/output/path

Content File Format (post.txt)

Title: May 27th
----
Uuid: abc123def456
----
Text:
Original caption with @mentions converted to Kirby links
----
Tags: art, travel, food
----

Transformations

• @mentions → (link: https://instagram.com/username text:@username)
• Hashtags → Extracted to Tags field (deduplicated, alphabetical)
• Pure hashtag lines → Moved to Tags field
• Line breaks → Preserved as-is
• Profile pictures (media-only posts) → Skipped

Configuration

Environment Variables

For CI/CD environments, you can set:

• KIRBY_INSTAGRAM_SOURCE - Source directory path
• KIRBY_INSTAGRAM_FEED - Output feed directory

Acknowledgments

• Instaloader - Instagram data export tool
• KirbyCMS - Flexible, file-based CMS

License

MIT License - See LICENSE for details.

Contributing

Issues and pull requests welcome at Codeberg.