README

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

Install Instaloader

Export your Instagram data:

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

Or for specific profile:

instaloader profile:yourusername

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.

emiland / kirby-instagram-importer

Maintainers

Package info

Statistics

Security