Step-by-Step: Migrating Your Instagram Archive to a Self-Hosted WordPress Gallery

Thomas at work in the garage, building a box
Thomas at work in the garage, building a box

A companion walkthrough to “Rebuilding My Photography Section.” Follow these steps in order. Each step notes which of the accompanying files (if any) you’ll need.

Files referenced in this guide:

  • sample-import-columns.csv
  • import-template-snippet.html
  • photography-grid.css
  • month-headings.js
Zip file of resources here

Step 1: Request your Instagram archive

Files needed: none

  1. Open the Instagram app → Settings → Accounts Center → Your information and permissions → Download your information.
  2. Choose your account, select JSON as the format, and submit the request.
  3. Wait for Instagram’s email (can take a few hours to a day), then download the .zip file it links to.

You don’t need any third-party tool for this step — it’s a native Instagram feature.

Step 2: Turn the raw export into an import-ready CSV

File needed: sample-import-columns.csv

  1. Unzip your Instagram archive and locate the JSON file containing your posts (usually under a content or your_instagram_activity folder, filename varies by export version).
  2. Open sample-import-columns.csv to see the exact column structure you’re aiming for: post_id, post_title, post_content, post_excerpt, post_date, image_count, images, latitude, longitude, is_carousel.
  3. Hand your raw JSON to an AI assistant (Claude or similar) along with that sample CSV, and ask it to convert your posts into matching rows. Key things to get right:
    • post_date needs to convert from Instagram’s raw timestamp into a normal date format WordPress can parse.
    • images should be a single filename for single-image posts, or a comma-separated list for carousels (see row 3 in the sample file for the format).
    • is_carousel should be yes or no — this matters later, in Step 5.
  4. Save the result as your own CSV, ready to upload.

Step 3: Install WP All Import and upload your images

Files needed: none yet (images only)

  1. Install WP All Import (free version works for a first attempt; Pro adds scheduling and more mapping flexibility — see resources-and-links.md for the plugin link).
  2. Upload your actual photo files to your server, typically via cPanel File Manager or FTP, into /wp-content/uploads/wpallimport/files/. The filenames must exactly match what’s listed in your CSV’s images column.

Step 4: Build the import template

File needed: import-template-snippet.html

  1. In WP All Import, start a New Import, upload your CSV from Step 2, and select Posts as the target content type.
  2. Map your CSV columns to WordPress fields (Title, Content, Excerpt, Date) using WP All Import’s drag-and-drop interface.
  3. In the Title & Content step, open import-template-snippet.html and copy its structure into your content template — specifically, make sure your image is wrapped in a link pointing at the image file (not just a bare <img> tag). This is what makes lightbox plugins work later, in Step 6.
  4. In the Images section of the import settings, choose “Use images currently uploaded in wp-content/uploads/wpallimport/files/” and set the field value to {images[1]}.
  5. Run the import.

Step 5: Find and fix broken carousel posts

File needed: import-template-snippet.html (reference the carousel warning at the bottom)

The {images[1]} syntax only reliably grabs the first image for single-image posts. Posts where is_carousel was yes will likely show a broken image icon instead.

  1. After the import finishes, check WP All Import → Manage Imports → History Logs for your import job.
  2. Search the log for “not a valid image” — each instance tells you which post broke and lists the filenames involved.
  3. For each affected post:
    • Open it in the WordPress editor.
    • Delete the broken image block.
    • Insert a native Gallery block and add all of that post’s images (they should already be sitting in your wpallimport/files/ folder — check your Media Library, or upload manually if any are missing).
    • Set the gallery’s Link to setting to Media File — this is required for the lightbox step next.
    • Update the post.

Step 6: Add lightbox functionality

Files needed: none (plugin-only step)

  1. Install a lightbox plugin — Simple Lightbox is what this project used (free, see resources-and-links.md).
  2. Activate it. Because your images are already wrapped in links pointing to the image files (from Step 4’s template, and from setting “Link to Media File” in Step 5’s galleries), the lightbox should work immediately on both single-image and gallery posts — no extra configuration needed for basic functionality.
  3. Test by clicking an image on a live post. It should open in an overlay rather than navigating away from the page.

Step 7: Style the archive/category grid

File needed: photography-grid.css

  1. Open photography-grid.css and read through the comments — it’s written for a Blocksy theme’s native .entries / .entry-cardmarkup. If you’re on a different theme, you’ll need to inspect your own archive page’s HTML (right-click a photo card → Inspect) and adjust the class names throughout the file to match.
  2. Once adjusted, paste the full stylesheet into your theme’s custom CSS area (in WordPress, usually Appearance → Customize → Additional CSS).
  3. Publish and check your live archive/category page. You should see a responsive grid — 3 columns on desktop, 2 on tablet, 1 on mobile — with photos keeping their natural aspect ratio instead of being force-cropped.
  4. If your images are stretching or cropping oddly, the most common cause is your theme adding an inline object-fitstyle directly on the <img> tag, which can override plain CSS. The !important flag already included in photography-grid.css on the object-fit rule is there specifically to handle this — if you’re still seeing issues, that’s the property to double check first via Inspect Element.

Step 8: Add month/year section headings

Files needed: month-headings.js, plus the .month-heading CSS rule already included in photography-grid.css

  1. Install a code snippets plugin — WPCode is what this project used (free “Lite” version is sufficient; see resources-and-links.md).
  2. In WPCode, create a new snippet, set its type to JavaScript, and paste in the full contents of month-headings.js.
  3. Adjust the category-photography selector inside the script if your archive page uses a different class name (it should match whatever you used in Step 7’s CSS file).
  4. Set the snippet’s Insertion → Location to Site Wide Header, then activate and save it.
  5. Confirm the .month-heading CSS rule from photography-grid.css (Step 7) is already in place — the script generates the heading elements, but the CSS is what makes them display correctly as full-width section breaks within the grid.
  6. Publish, hard-refresh your archive page, and confirm month/year headings appear above the correct groups of photos, most recent first.

Step 9: Disable infinite scroll (if your theme uses it)

Files needed: none — one CSS rule, already included in photography-grid.css

If your archive page auto-loads more photos as you scroll and you’d rather have standard numbered pagination, check whether your theme is generating both mechanisms in the same markup (many themes, including Blocksy, render normal numbered page links and an invisible auto-load trigger element at the same time).

The rule targeting .ct-load-more-helper in photography-grid.css is Blocksy-specific — if you’re on a different theme, inspect the bottom of your archive page’s HTML for a similarly-purposed hidden trigger element, and hide that instead.

Step 10: Set up your repeat-import routine

Files needed: sample-import-columns.csv (as your ongoing template)

Since Instagram’s export is a manual, on-demand action rather than a live feed, there’s no way to fully automate new posts flowing in. The repeatable version of this workflow:

  1. Every month or two (or whenever you’ve built up a batch of new posts), request a fresh Instagram archive (Step 1).
  2. Identify which posts are new since your last import (check your last import’s date in WP All Import’s history).
  3. Build a CSV of just the new posts, following the same column structure as sample-import-columns.csv (Step 2).
  4. Re-run your existing WP All Import template (Step 4) — it will match against existing posts by title and only create the new ones, not duplicate anything.
  5. Check for and fix any new carousel posts (Step 5).

Everything else — lightbox, grid styling, month headings, pagination — is already in place and will automatically apply to newly imported posts.