Squarespace Migration CLI

Move from Squarespace to Astro with s2a

s2a extracts content from Squarespace and generates an editable Astro project. Use this page for the fastest path from install to your first migration.

Current release

v0.5.7 includes redirect output (--emit-redirects), route-based localised assets, high-fidelity layout strategies, and compatibility upgrades for legacy hash-suffixed asset manifests.

Read user guide Download releases Open repository

Quick start

Install

brew tap krahd/tap
brew install s2a

First migration

s2a migrate https://example.squarespace.com \\
  --astro-dir ./generated/example-site

Before you run

What s2a generates

A structured site snapshot and a buildable Astro project with route pages, layouts, site data, and localised assets under readable route-based filenames.

What you need

Site URL, disk space for the output folder, and Node.js only when you want to run the generated Astro site locally.

When to use authentication

Public pages can usually be crawled directly. For account-authenticated content, use credentials or browser storage-state with the auth options.

Current boundaries

Commerce, events, forms, members, and full Squarespace admin workflows are out of scope. Utility routes such as /cart, /checkout, and /account are intentionally excluded from static output.

Migration patterns

Merge XML export when available

s2a migrate https://example.squarespace.com \\
  --xml-export ./exports/squarespace-wordpress.xml \\
  --astro-dir ./generated/example-site

Use fidelity controls for layout-heavy pages

s2a migrate https://example.squarespace.com \\
  --fidelity-mode high \\
  --layout-strategy components \\
  --markdown \\
  --astro-dir ./generated/example-site

If you omit --output-dir, s2a writes a timestamped run folder in site-output/ and records key paths in execution-metadata.json.

Authentication for private content

Public sites normally do not need authentication. For account-authenticated routes, export credentials before running probe, crawl, auth-browser, or migrate: 

export SQUARESPACE_USER=owner@example.com
export SQUARESPACE_PWD=owner-password

s2a migrate https://example.squarespace.com \
  --astro-dir ./generated/example-site
  • --username and --password override environment variables for one run.
  • --site-password is for a site-wide gate, separate from account login.
  • The browser-auth flow does not support interactive 2FA prompts.

What s2a writes

Run folder

  • execution-metadata.json
  • probe.json
  • site_snapshot.json
  • report.json
  • asset_manifest.json and downloaded-assets/
  • raw-html/ and raw-json/

Generated Astro site

  • migration-manifest.json
  • src/content/pages/
  • src/content/posts/ when posts were detected
  • src/data/site.json
  • public/assets/ for localized media and files
  • src/layouts/, src/pages/, and optional redirect outputs

Continue in Astro

The generated output is a normal Astro project. After migration, move into the generated directory and start the local preview: 

cd ./generated/example-site
npm install
npm run dev

Most hand edits happen in src/content/ for content, src/data/site.json for site metadata and navigation, and src/layouts/ or src/pages/ for the final Astro presentation.

Current limitations and scope

  • 2FA is not supported in the automated browser-auth flow.
  • Commerce, events, forms, members, and full Squarespace admin automation are not migrated.
  • Redirect generation exists, but redirect mappings should still be reviewed before production.
  • The generated Astro project should be reviewed and edited before production use.

Documentation