Add Wix migrate tool

README.md

@@ -26,6 +26,7 @@ Each tool has its own detailed documentation:
 - [Substack members](https://github.com/TryGhost/migrate/tree/main/packages/mg-substack-members-csv)
 - [Tiny News](https://github.com/TryGhost/migrate/tree/main/packages/mg-tinynews)
 - [Tiny News Members](https://github.com/TryGhost/migrate/tree/main/packages/mg-tinynews-members)
+- [Wix CSV](https://github.com/TryGhost/migrate/tree/main/packages/mg-wix-csv)
 - [WordPress API](https://github.com/TryGhost/migrate/tree/main/packages/mg-wp-api)
 - [WordPress XML](https://github.com/TryGhost/migrate/tree/main/packages/mg-wp-xml)
 

packages/mg-wix-csv/.eslintrc.cjs

@@ -0,0 +1,15 @@
+module.exports = {
+    parser: '@typescript-eslint/parser',
+    plugins: ['ghost'],
+    extends: [
+        'plugin:ghost/node'
+    ],
+    rules: {
+        'no-unused-vars': 'off',
+        'no-undef': 'off',
+        'ghost/ghost-custom/no-native-errors': 'off',
+        'ghost/ghost-custom/no-native-error': 'off',
+        'ghost/ghost-custom/ghost-error-usage': 'off',
+        'ghost/filenames/match-regex': 'off'
+    }
+};

packages/mg-wix-csv/.gitignore

@@ -0,0 +1,4 @@
+/build
+/tsconfig.tsbuildinfo
+/tmp
+.env

packages/mg-wix-csv/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2013-2026 Ghost Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/mg-wix-csv/README.md

@@ -0,0 +1,56 @@
+# Wix CSV Migration
+
+Migrate Wix blog posts from a posts CSV export into a Ghost import file.
+
+## Usage
+
+```bash
+migrate wix-csv --posts /path/to/posts.csv --url https://example.com
+```
+
+By default, the command reads posts, converts Wix rich content to Ghost-compatible HTML/Lexical, downloads Wix-hosted assets, and writes a Ghost import zip.
+
+## Options
+
+| Option                  | Type    | Default  | Description                                                                                                         |
+|-------------------------|---------|----------|---------------------------------------------------------------------------------------------------------------------|
+| `--posts`               | string  | `null`   | Path to the Wix posts CSV file. Required.                                                                           |
+| `--url`                 | string  | `null`   | URL to the live Wix site, used for source URLs and link fixing. Required.                                           |
+| `--defaultAuthorName`   | string  | `null`   | Fallback author name when the CSV row has no author.                                                                |
+| `--scrape`              | array   | `assets` | Asset scraping mode. Use `assets`, `img`, `media`, or `files` to download assets; use `none` to skip.               |
+| `--includeMainCategory` | boolean | `true`   | Include the `Main Category` column as Ghost tags. Note: option name intentionally matches the current CLI spelling. |
+| `--includeCategories`   | boolean | `true`   | Include the `Categories` column as Ghost tags. Supports plain category names and legacy JSON arrays.                |
+| `--includeTags`         | boolean | `true`   | Include the `Tags` column as Ghost tags.                                                                            |
+| `--tmpPath`             | string  | `null`   | Full path for temporary migration files. Defaults to the migrator cache location.                                   |
+| `--outputPath`          | string  | `null`   | Full path where the final zip should be saved. Defaults to the current working directory.                           |
+| `--cacheName`           | string  | `null`   | Custom cache name. Defaults to a name derived from the site URL.                                                    |
+| `--cache`               | boolean | `true`   | Keep the local cache after migration completes. Only applies when `--zip` is enabled.                               |
+| `--zip`                 | boolean | `true`   | Create a Ghost import zip. Set to `false` to write only the import JSON/cache output.                               |
+| `-V`, `--verbose`       | boolean | `false`  | Show verbose output. Defaults to `true` when `DEBUG` is set.                                                        |
+| `--veryVerbose`         | boolean | `false`  | Show very verbose output. Implies `--verbose`.                                                                      |
+| `--ghostApiUrl`         | string  | `null`   | Ghost site URL used to fetch existing users for author matching.                                                    |
+| `--ghostAdminKey`       | string  | `null`   | Ghost Admin API key used with `--ghostApiUrl`.                                                                      |
+
+## Taxonomy
+
+The migrator always adds the internal source tag `#wix`.
+
+CSV taxonomy fields are controlled independently:
+
+```bash
+migrate wix-csv --posts /path/to/posts.csv --url https://example.com --includeMainCategory false --includeCategories true --includeTags false
+```
+
+For updated Wix CSV exports, `Categories` may contain readable names such as `Tax Planning`. Older exports may contain JSON arrays of IDs. The migrator accepts both formats.
+
+## Content Notes
+
+- `Rich Content` is used as the source of post body HTML.
+- `Plain Content` is used as fallback content when `Rich Content` is empty or invalid.
+- `Internal ID` is mapped to Ghost `comment_id`.
+- Wix image URLs are converted to original static media URLs, for example `https://static.wixstatic.com/media/<media-id>`.
+
+
+# Copyright & License
+
+Copyright (c) 2013-2026 Ghost Foundation - Released under the [MIT license](LICENSE).

packages/mg-wix-csv/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@tryghost/mg-wix-csv",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TryGhost/migrate.git",
+    "directory": "packages/mg-wix-csv"
+  },
+  "author": "Ghost Foundation",
+  "license": "MIT",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/types.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./build/index.js"
+    }
+  },
+  "scripts": {
+    "dev": "echo \"Implement me!\"",
+    "build:watch": "tsc --watch --preserveWatchOutput --sourceMap",
+    "build": "tsc --build --sourceMap",
+    "lint": "eslint src/ --ext .ts --cache",
+    "test": "c8 --src src --all --check-coverage --100 --reporter text --reporter cobertura node --test 'build/test/**/*.test.js'",
+    "test:local": "pnpm build && pnpm test",
+    "posttest": "pnpm lint"
+  },
+  "files": [
+    "build"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.4",
+    "@typescript-eslint/parser": "8.59.4",
+    "c8": "11.0.0",
+    "eslint": "8.57.1",
+    "typescript": "6.0.3"
+  },
+  "dependencies": {
+    "@tryghost/errors": "3.0.3",
+    "@tryghost/kg-default-cards": "10.2.10",
+    "@tryghost/mg-fs-utils": "workspace:*",
+    "@tryghost/string": "0.3.1",
+    "simple-dom": "1.4.0"
+  }
+}

packages/mg-wix-csv/src/index.ts

@@ -0,0 +1,10 @@
+import {mapContent} from './lib/mapper.js';
+
+export default async (args: {options: any}) => {
+    const result = await mapContent(args);
+    return result;
+};
+
+export {
+    mapContent
+};

packages/mg-wix-csv/src/lib/mapper.ts

@@ -0,0 +1,215 @@
+import errors from '@tryghost/errors';
+import fsUtils from '@tryghost/mg-fs-utils';
+import {slugify} from '@tryghost/string';
+import {richContentToHtml} from './rich-content.js';
+import {wixImageUriToUrl} from './wix-image.js';
+
+const parsePostsCSV = async ({pathToFile}: {pathToFile: string}) => {
+    const parseCSV = fsUtils.csv.parseCSV;
+    const parsed = await parseCSV(pathToFile);
+
+    return parsed as wixCSVPostDataObject[];
+};
+
+const parseDate = (value?: string) => {
+    if (!value) {
+        return null;
+    }
+
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+};
+
+const parseBoolean = (value?: string) => {
+    return typeof value === 'string' && value.toLowerCase() === 'true';
+};
+
+const parseIdArray = (value?: string) => {
+    if (!value) {
+        return [];
+    }
+
+    const trimmed = value.trim();
+
+    if (trimmed.length === 0) {
+        return [];
+    }
+
+    try {
+        const parsed = JSON.parse(trimmed);
+
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+
+        return parsed.filter((item): item is string => typeof item === 'string' && item.length > 0);
+    } catch (error) {
+        return [trimmed];
+    }
+};
+
+const uniqueIds = (ids: string[]) => {
+    return [...new Set(ids.filter(Boolean))];
+};
+
+const looksLikeWixId = (value: string) => {
+    return /^[a-f0-9]{24}$/i.test(value);
+};
+
+const createTag = (value: string) => {
+    const slug = looksLikeWixId(value) ? value : slugify(value);
+
+    return {
+        url: `migrator-added-tag-${slug}`,
+        data: {
+            slug,
+            name: value
+        }
+    };
+};
+
+const createAuthor = ({name, defaultAuthorName}: {name?: string, defaultAuthorName?: string}) => {
+    const authorName = name?.trim() || defaultAuthorName?.trim() || 'Author';
+    const authorSlug = slugify(authorName);
+
+    return {
+        url: `migrator-added-author-${authorSlug}`,
+        data: {
+            slug: authorSlug,
+            name: authorName,
+            email: `${authorSlug}@example.com`
+        }
+    };
+};
+
+const buildPostUrl = ({url, path}: {url?: string, path?: string}) => {
+    if (!url || !path) {
+        return path || '';
+    }
+
+    if (path.startsWith('http://') || path.startsWith('https://')) {
+        return path;
+    }
+
+    return `${url}${path.startsWith('/') ? '' : '/'}${path}`;
+};
+
+const createSlug = ({slug, title}: {slug?: string, title?: string}) => {
+    if (slug && slug.trim().length > 0) {
+        return slugify(slug);
+    }
+
+    return slugify(title || 'untitled');
+};
+
+const shouldInclude = (value: boolean | undefined) => {
+    return value !== false;
+};
+
+const mapTags = (postData: wixCSVPostDataObject, options?: any) => {
+    const categories = parseIdArray(postData.Categories);
+    const tags = parseIdArray(postData.Tags);
+    const mainCategory = postData['Main Category'];
+    const includeMainCategory = shouldInclude(options?.includeMainCategory);
+    const includeCategories = shouldInclude(options?.includeCategories);
+    const includeTags = shouldInclude(options?.includeTags);
+    const shouldDropLegacyMainCategoryId = mainCategory && !looksLikeWixId(mainCategory) && categories[0] && looksLikeWixId(categories[0]);
+    const secondaryCategories = shouldDropLegacyMainCategoryId ? categories.slice(1) : categories;
+    const orderedCategories = uniqueIds([
+        ...(includeMainCategory && mainCategory ? [mainCategory] : []),
+        ...(includeCategories ? secondaryCategories : [])
+    ]);
+
+    return [
+        ...uniqueIds([
+            ...orderedCategories,
+            ...(includeTags ? tags : [])
+        ]).map(createTag),
+        {
+            url: 'migrator-added-tag-hash-wix',
+            data: {
+                slug: 'hash-wix',
+                name: '#wix'
+            }
+        }
+    ];
+};
+
+const mapPost = ({postData, options}: {postData: wixCSVPostDataObject, options?: any}) => {
+    const publishedAt = parseDate(postData['Published Date']);
+    const updatedAt = parseDate(postData['Last Published Date']) || publishedAt;
+    const createdAt = publishedAt || updatedAt || new Date();
+    const postSlug = createSlug({slug: postData.Slug, title: postData.Title});
+    const featureImage = wixImageUriToUrl(postData['Cover Image']);
+
+    const mappedData: mappedDataObject = {
+        url: buildPostUrl({url: options?.url, path: postData['Post Page URL']}),
+        data: {
+            slug: postSlug,
+            comment_id: postData['Internal ID'] || null,
+            published_at: publishedAt,
+            updated_at: updatedAt,
+            created_at: createdAt,
+            title: postData.Title || postSlug,
+            type: 'post',
+            html: richContentToHtml({
+                richContent: postData['Rich Content'],
+                plainContent: postData['Plain Content']
+            }),
+            plaintext: postData['Plain Content'] || null,
+            status: publishedAt ? 'published' : 'draft',
+            custom_excerpt: postData.Excerpt || null,
+            visibility: 'public',
+            featured: parseBoolean(postData.Featured),
+            tags: mapTags(postData, options),
+            author: createAuthor({
+                name: postData.Author,
+                defaultAuthorName: options?.defaultAuthorName
+            })
+        }
+    };
+
+    if (featureImage) {
+        mappedData.data.feature_image = featureImage;
+    }
+
+    return mappedData;
+};
+
+const mapPosts = async ({pathToFile, options}: {pathToFile: string, options: any}) => {
+    const parsed = await parsePostsCSV({pathToFile});
+
+    return parsed.map((postData: wixCSVPostDataObject) => {
+        return mapPost({postData, options});
+    });
+};
+
+const mapContent = async (args: {options: any}) => {
+    const output = {
+        posts: [] as mappedDataObject[]
+    };
+
+    const mappedPosts = await mapPosts({pathToFile: args.options.posts, options: args.options});
+
+    if (mappedPosts.length < 1) {
+        throw new errors.NoContentError({message: 'Input file is empty'});
+    }
+
+    output.posts = mappedPosts;
+
+    return output;
+};
+
+export {
+    buildPostUrl,
+    createAuthor,
+    createSlug,
+    mapContent,
+    mapPost,
+    mapTags,
+    parseBoolean,
+    parseDate,
+    parseIdArray,
+    parsePostsCSV,
+    uniqueIds
+};