Purpose

Marketing Sux Content Magic is a private WordPress plugin built for the Marketing Sux agency content workflow.

The plugin is not meant to generate content inside WordPress. Its purpose is to move approved, structured content from AI-assisted writing workflows into WordPress cleanly, safely, and repeatably.

The core workflow is:

1. A human installs the plugin on a WordPress site.
2. The human exports a site template JSON from the plugin.
3. The human gives that template JSON to AI.
4. AI reads the field structure, post types, taxonomies, options pages, and template slots.
5. AI generates a matching Content Magic import JSON.
6. The human uploads the import JSON into WordPress.
7. The plugin validates/dry-runs the package.
8. The human imports the package as draft content or patch updates.
9. The human spot-checks and publishes manually.

This lets AI create content that fits the exact ACF structure of each client site without requiring manual CSV mapping, WP All Import setup, or copy/paste into WordPress fields.

Plugin Name and Versioning

Visible plugin name:

Marketing Sux Content Magic

Admin menu:

Tools → Content Magic

Current tested version during documentation:

0.2.6

Important naming rule:

The plugin name should not include the version number. Version numbers belong in the plugin header and internal constants only.

What the Plugin Does

Marketing Sux Content Magic supports:

• Exporting site template JSON
• Exporting content inventory JSON
• Exporting full content snapshots
• Exporting selected content
• Exporting options values
• Exporting taxonomies and terms
• Importing mapped JSON packages
• Creating new WordPress pages
• Updating existing WordPress pages
• Creating/updating posts
• Creating/updating custom post type entries
• Updating ACF fields
• Updating ACF Options Page fields
• Updating Rank Math SEO metadata
• Assigning taxonomy terms
• Creating taxonomy terms when needed
• Deleting taxonomy terms through cleanup packages
• Trashing, restoring, or deleting post objects by import action

The plugin is designed around patch-safe imports.

Core Safety Rule

The most important behavior:

Missing field = preserve existing content

Included field = update that field

Included blank field = intentionally clear that field

Example:

"acf": {
  "hero_heading_h2": "New Hero Heading"
}

Only hero_heading_h2 updates. Other ACF fields stay untouched.

Example intentional clear:

"acf": {
  "hero_value_prop_3": ""
}

This clears only hero_value_prop_3.

AI must not include blank fields unless the human intends to clear those fields.

What AI Should Ask For

When creating an import JSON, AI should ask for or use:

1. The latest Site Template JSON from the target WordPress site.
2. The desired content type:
   • new landing page
   • existing page update
   • CPT entry
   • options page/global content update
   • cleanup package
3. Target details:
   • post type
   • slug
   • parent slug if needed
   • import key if available
   • page/CPT title
   • publish status, usually draft
4. Content inputs:
   • sitemap
   • focus keywords
   • client facts
   • brand voice
   • Surfer/SEO terms
   • existing content snapshot if rewriting
5. Whether the import should create new content, update existing content, or both.

The AI should not guess field names. It should use the uploaded site template.

Site Template JSON

The Site Template JSON tells AI what the site accepts.

It includes:

• site info
• plugin detection
• post types
• taxonomies
• options pages
• ACF template slots
• ACF field groups
• field labels
• field names
• field keys
• field types
• field requirements
• field instructions
• recommended targets

Important package type:

"package_type": "mscm_site_template"

AI should treat this file as the source of truth for field names and target structures.

Template Slots

A template slot represents an importable content model.

Examples from the tested template site:

• business-info
• global-content
• landing-pages
• location-info
• project-info
• team-info
• review
• brand
• product

Each template slot corresponds to an ACF field group or content structure.

A template slot answers:

What field structure am I filling?

A target answers:

Where should this content go?

Every import item should include both.

Content Import JSON

Import package type:

"package_type": "mscm_content_import"

Typical top-level structure:

{
  "package_type": "mscm_content_import",
  "package_version": "0.2.6",
  "package_name": "Example Import Package",
  "default_import_mode": "upsert",
  "field_update_mode": "patch",
  "items": []
}

Recommended defaults

For new content:

"default_import_mode": "upsert",
"field_update_mode": "patch"

For existing-only updates:

"default_import_mode": "update_only",
"field_update_mode": "patch"

Import Modes

Common modes:

upsert

Update if existing. Create if missing.

Best for new landing pages or CPT entries.

update_only

Only update an existing target. Do not create if missing.

Best for patch updates, cleanup, or options pages.

create_only

Create only. Skip/error if it already exists.

Useful when duplicates would be dangerous.

Target Types

The plugin supports multiple target types.

Target Type: Post Object

Used for:

• pages
• posts
• CPT entries

Example:

{
  "template_slot": "landing-pages",
  "import_mode": "upsert",
  "target": {
    "target_type": "post_object",
    "post_type": "page",
    "match_by": "import_key",
    "import_key": "service_page_roof_replacement",
    "slug": "roof-replacement",
    "create_if_missing": true,
    "update_if_exists": true
  },
  "post": {
    "post_title": "Roof Replacement",
    "post_name": "roof-replacement",
    "post_status": "draft"
  },
  "acf": {
    "hero_heading_h2": "Roof Replacement Done Right"
  }
}

Matching Existing Content

Preferred matching methods:

1. Match by import key

Best long-term method.

"match_by": "import_key",
"import_key": "demo_service_page_website_design"

The plugin stores this import key as post meta:

_mscm_import_key

This is durable even if the slug changes later.

2. Match by ID

Precise, but not portable across environments.

"match_by": "id",
"post_id": 610

Useful for updates on a known site.

3. Match by slug

Good for simple top-level pages.

"match_by": "slug",
"slug": "website-design"

4. Match by slug + parent

Useful for child pages.

"match_by": "slug_parent",
"slug": "seo-services",
"parent_slug": "marketing-services"

Parent/Child Page Imports

Parent pages can be created earlier in the same import package, and child pages can target them later in the same package.

The parent item should appear before the child item.

Example child target:

"target": {
  "target_type": "post_object",
  "post_type": "page",
  "match_by": "import_key",
  "import_key": "test_child_seo_services",
  "slug": "seo-services",
  "path": "marketing-services/seo-services",
  "parent_slug": "marketing-services",
  "require_parent": true,
  "create_if_missing": true,
  "update_if_exists": true
}

Important:

require_parent: true should be used when the child must not import without its parent.

Updating Slugs and Parents

The plugin treats target.slug as a lookup value by default.

It does not force-update the existing post slug unless explicitly told.

To update a slug:

"target": {
  "update_slug": true
}

To update a parent:

"target": {
  "update_parent": true
}

This prevents accidental URL changes during ACF-only patch updates.

Target Type: ACF Options

Used for:

• Business Info
• Global Content
• site-wide reusable content
• options page fields

Example:

{
  "template_slot": "business-info",
  "import_mode": "update_only",
  "target": {
    "target_type": "acf_options",
    "options_post_id": "options",
    "options_page_slug": "business-info"
  },
  "acf": {
    "business_name": "Example Company",
    "primary_phone_number_display": "(555) 555-5555"
  }
}

Important:

The tested template used:

"options_post_id": "options"

Some ACF setups may use option instead. AI should read the Site Template JSON and follow the exported value.

Target Type: Taxonomy Term

Used for deleting taxonomy terms or future term-specific operations.

Example delete:

{
  "template_slot": "taxonomy-cleanup",
  "import_mode": "update_only",
  "action": "delete",
  "target": {
    "target_type": "taxonomy_term",
    "taxonomy": "sales-category",
    "slug": "demo-products"
  }
}

Post Object Lifecycle Actions

Supported actions include:

Trash

"action": "trash"

Moves the target post/page/CPT to Trash.

Delete

"action": "delete"

Hard delete. Use carefully.

Restore

"action": "restore"

Restores a trashed item.

Example:

{
  "template_slot": "landing-pages",
  "import_mode": "update_only",
  "action": "trash",
  "target": {
    "target_type": "post_object",
    "post_type": "page",
    "match_by": "import_key",
    "import_key": "test_page_google_ads_management",
    "include_trash": true,
    "create_if_missing": false,
    "update_if_exists": true
  }
}

Taxonomies

The plugin can assign and create terms.

Example:

"taxonomies": {
  "sales-category": {
    "append": false,
    "terms": [
      {
        "name": "Website Services",
        "slug": "website-services",
        "create_if_missing": true
      }
    ]
  }
}

Rules:

• append: false replaces the target object’s terms for that taxonomy.
• append: true adds terms without removing existing ones.
• Omitted taxonomies are preserved.
• Included taxonomy with an empty term array may clear that taxonomy assignment depending on plugin behavior.

AI should only include taxonomies intentionally.

SEO Fields

The plugin supports Rank Math metadata.

Example:

"seo": {
  "focus_keyword": "website design",
  "seo_title": "Website Design Services | Marketing Sux",
  "seo_description": "Get a conversion-focused website built around clear messaging, clean structure, and practical SEO foundations.",
  "robots": ["noindex"]
}

In previous tests, the plugin successfully set:

• Rank Math focus keyword
• Rank Math SEO title
• Rank Math meta description
• Rank Math robots/noindex

AI should include SEO fields when creating SEO-focused pages.

ACF Fields

ACF values go under the acf object.

Example:

"acf": {
  "hero_pre_heading_h1": "Website Design",
  "hero_heading_h2": "Websites Built To Generate Better Leads",
  "hero_content": "<p>Approved rich text content here.</p>",
  "body_3": "<h2>Longform Section</h2><p>Longform content here.</p>"
}

The plugin maps by field name/key using the exported site template.

AI should use the exact field names from the Site Template JSON.

WYSIWYG Fields

For WYSIWYG fields, AI should provide HTML strings:

"body_1_content": "<p>Paragraph text.</p><ul><li>Bullet item</li></ul>"

This is intentional. The website viewer sees rich text, and WordPress stores it correctly.

Textarea Fields

For textarea fields, AI should usually provide plain text unless the field instructions suggest otherwise.

Image Fields

Current best practice:

• Omit image fields unless intentionally updating/clearing them.
• Blank image fields only if the human wants to clear them.
• Image sideloading is not the priority workflow yet.

Important AI Rule: Do Not Include Empty Fields Casually

Because blank fields clear content, AI should avoid generating every field with empty strings.

Bad for patch updates:

"acf": {
  "hero_heading_h2": "New Heading",
  "body_3": ""
}

This would clear body_3.

Good:

"acf": {
  "hero_heading_h2": "New Heading"
}

Only update what the human asked to update.

Export Types

The plugin has multiple export types.

Site Template JSON

Use this when AI needs to understand the site structure and field mapping.

Taxonomies + Terms JSON

Use this when AI needs existing taxonomy terms.

Content Inventory JSON

Use this when AI needs a lightweight list of existing posts/pages/CPTs.

Full Content Snapshot JSON

Use this when AI needs current content values, ACF values, SEO fields, post content, excerpts, taxonomies, and metadata.

Selected Content JSON

Use this when AI only needs specific pages, posts, CPTs, or options fields.

Options Values JSON

Use this when AI needs current Business Info / Global Content / options page values.

Clean Snapshot vs Developer Snapshot

Future improvement idea:

The current full snapshot can be noisy because it includes internal meta fields from Elementor, Rank Math, Brevo/SIB, ACF references, etc.

A future version should offer:

Clean Snapshot

Includes only:

• title
• slug
• post type
• status
• parent
• menu order
• taxonomies
• SEO fields
• ACF values
• post content/excerpt

Developer Snapshot

Includes all meta/debug data.

Tested Workflow Summary

The following behaviors were tested successfully:

• Site template export
• Full content snapshot export
• Single service page import
• ACF field mapping on landing page
• Rank Math metadata import
• Taxonomy term creation and assignment
• Small ACF-only update
• ACF-only update without calling wp_insert_post()
• Missing field preservation
• Intentional blank field clear
• Batch page creation
• Parent page and child page creation in the same import
• Review CPT import
• Mixed CPT import
• Location CPT ACF fields
• Team Member CPT ACF fields
• Options page updates for Business Info
• Options page updates for Global Content
• Cleanup file to trash dummy pages/CPTs
• Taxonomy term deletion
• Lifecycle actions: trash/delete/restore support added
• Template export detects new ACF fields after field group changes

A funny field-change test confirmed that the template export correctly detected a newly added ACF field named fuck_you in the Landing Pages field group. This proved that future exports reflect current ACF field changes.

Standard Human + AI Workflow

New page build

Human provides:

• Site Template JSON
• page list
• slugs
• parent slugs if needed
• focus keywords
• client facts
• content notes

AI returns:

• Content Magic import JSON

Human does:

1. Upload JSON.
2. Run Validate / Dry Run.
3. Review preview.
4. Import as draft.
5. Spot-check frontend/template rendering.
6. Publish manually.

Existing page rewrite workflow

Human provides:

• Site Template JSON
• Selected Content JSON or Full Content Snapshot JSON
• instructions on what to rewrite

AI returns:

• Patch-style import JSON containing only fields that should change.

Human validates and imports.

AI must preserve fields unless explicitly changing them.

Global content workflow

Human provides:

• Site Template JSON
• Options Values JSON if preserving or rewriting existing global content
• instructions for Business Info or Global Content updates

AI returns:

• acf_options import JSON

Important:

Globals should not be included in normal page imports unless intentionally updating global/options data.

Cleanup workflow

Human asks for cleanup JSON.

AI creates a package using:

• action: trash for dummy pages/posts/CPTs
• action: delete for dummy taxonomy terms
• blank ACF values only for dummy options fields that should be cleared

AI should avoid hard deleting posts unless the human explicitly asks.

Example: New Landing Page Import Item

{
  "template_slot": "landing-pages",
  "import_mode": "upsert",
  "target": {
    "target_type": "post_object",
    "post_type": "page",
    "match_by": "import_key",
    "import_key": "service_page_website_design",
    "slug": "website-design",
    "path": "website-design",
    "create_if_missing": true,
    "update_if_exists": true
  },
  "post": {
    "post_title": "Website Design",
    "post_name": "website-design",
    "post_status": "draft",
    "post_excerpt": "Website design services built for clearer messaging, stronger conversion paths, and better lead generation.",
    "menu_order": 120
  },
  "seo": {
    "focus_keyword": "website design",
    "seo_title": "Website Design Services | Marketing Sux",
    "seo_description": "Get a conversion-focused website built around clear messaging, clean structure, and practical SEO foundations."
  },
  "taxonomies": {
    "sales-category": {
      "append": false,
      "terms": [
        {
          "name": "Website Services",
          "slug": "website-services",
          "create_if_missing": true
        }
      ]
    }
  },
  "acf": {
    "wordpress_title": "Website Design",
    "wordpress_slug": "website-design",
    "wordpress_excerpt": "Website design services built for clearer messaging, stronger conversion paths, and better lead generation.",
    "seo_focus_keyword": "website design",
    "seo_meta_title": "Website Design Services | Marketing Sux",
    "seo_meta_description": "Get a conversion-focused website built around clear messaging, clean structure, and practical SEO foundations.",
    "hero_pre_heading_h1": "Website Design",
    "hero_heading_h2": "Websites Built To Generate Better Leads",
    "hero_content": "<p>A good website should do more than look decent. It should explain what you do, make the next step obvious, and support the search strategy behind the business.</p>",
    "hero_value_prop_1": "Clear Page Structure",
    "hero_value_prop_2": "Conversion-Focused Copy",
    "hero_value_prop_3": "SEO-Ready Builds",
    "body_1_heading_h2": "Website Design That Starts With The Business Goal",
    "body_1_content": "<p>We design websites around the way real customers make decisions.</p>",
    "body_2_heading_h2": "Built For SEO, Speed, And Easy Updates",
    "body_2_content": "<p>Your site should be easy to manage after launch.</p>",
    "body_3": "<h2>A Website Design Process That Does Not Start With Pretty Pictures</h2><p>Most bad website projects start in the wrong place.</p>",
    "faqs_heading": "Website Design FAQs",
    "faqs_intro": "A few common questions about building a better business website.",
    "faq_1_question": "What makes a website design good for lead generation?",
    "faq_1_answer": "A lead-focused website has clear messaging, strong calls to action, service-specific pages, simple navigation, and forms or phone actions that are easy to find.",
    "faq_2_question": "Do you build websites with SEO in mind?",
    "faq_2_answer": "Yes. Page structure, headings, metadata, internal linking, service pages, and location targeting should be planned before the site is designed.",
    "faq_3_question": "Can this type of site be updated after launch?",
    "faq_3_answer": "Yes. Structured ACF fields and reusable templates make it easier to update content, add pages, and keep layouts consistent over time.",
    "faq_4_question": "Is this imported as a draft?",
    "faq_4_answer": "Yes. Content Magic imports new page packages as drafts unless instructed otherwise.",
    "cta_heading": "Build A Website That Has A Job To Do",
    "cta_button_text": "Start Your Website Project",
    "cta_content": "<p>Ready for a site that looks better, reads clearer, and supports your lead-generation strategy?</p>"
  }
}

Example: Small Patch Update

{
  "package_type": "mscm_content_import",
  "package_version": "0.2.6",
  "package_name": "Small Patch Update",
  "default_import_mode": "update_only",
  "field_update_mode": "patch",
  "items": [
    {
      "template_slot": "landing-pages",
      "import_mode": "update_only",
      "target": {
        "target_type": "post_object",
        "post_type": "page",
        "match_by": "import_key",
        "import_key": "service_page_website_design",
        "create_if_missing": false,
        "update_if_exists": true
      },
      "acf": {
        "hero_heading_h2": "New Heading Only"
      }
    }
  ]
}

Example: Intentional Clear

{
  "acf": {
    "hero_value_prop_3": ""
  }
}

Only use this when the human wants to clear that field.

Example: Options Page Update

{
  "template_slot": "global-content",
  "import_mode": "update_only",
  "target": {
    "target_type": "acf_options",
    "options_post_id": "options",
    "options_page_slug": "global-content"
  },
  "acf": {
    "cta_heading": "Ready To Get Started?",
    "cta_button_text": "Contact Us",
    "cta_content": "<p>Contact the team to schedule your next step.</p>"
  }
}

Example: Cleanup Item

{
  "template_slot": "landing-pages",
  "import_mode": "update_only",
  "action": "trash",
  "target": {
    "target_type": "post_object",
    "post_type": "page",
    "match_by": "import_key",
    "import_key": "test_page_google_ads_management",
    "include_trash": true,
    "create_if_missing": false,
    "update_if_exists": true
  }
}

AI Operating Instructions

When an AI assistant is asked to use Marketing Sux Content Magic:

1. Ask for the latest Site Template JSON unless already provided.
2. If updating existing content, ask for a Selected Content JSON or Full Content Snapshot JSON.
3. Read the exact template_slots, post types, taxonomies, and options pages.
4. Use exact ACF field names from the template.
5. Do not invent fields.
6. Do not include empty fields unless intentionally clearing them.
7. Use draft status for new pages unless the human says otherwise.
8. Prefer match_by: import_key for durable updates.
9. Use unique import keys.
10. Use update_only for patch updates.
11. Use upsert for new page/CPT creation.
12. Include parent slugs only when needed.
13. Use require_parent: true when a child page must not be created at the top level.
14. Keep global/options fields out of page imports unless the human intentionally wants to update global content.
15. Run cleanup with action: trash, not hard delete, unless explicitly asked.
16. Tell the human to run Validate / Dry Run before importing.
17. Tell the human what the import is expected to create/update/clear/delete.
18. If the import touches options/global fields, clearly warn what fields are included, because blanks will clear values.

Human Operating Instructions

For the human using the plugin:

1. Install and activate Marketing Sux Content Magic on a staging or dev site first.
2. Go to Tools → Content Magic.
3. Export the Site Template JSON.
4. Give the JSON to AI.
5. Ask AI for a Content Magic import package.
6. Upload/paste the import package into Content Magic.
7. Run Validate / Dry Run.
8. Review every row:
   • template slot
   • target type
   • target
   • action
   • status
   • message
9. Import only after the dry run looks right.
10. Spot-check the WordPress admin and frontend.
11. Export a Full Snapshot or Selected Content JSON if verification is needed.
12. Publish manually after review.

Staging vs Production

Use staging first for:

• new client field groups
• legacy field sets
• new CPTs
• WooCommerce testing
• image field testing
• relationship field testing
• cleanup/delete actions

Production imports should be limited to already-tested packages and should still be dry-run first.

Known Limitations / Future Improvements

Potential future improvements:

• WooCommerce-specific product support
• Simple WooCommerce product import
• Variable product import
• Product attributes/variations
• Featured image sideloading
• ACF image field sideloading
• Gallery field imports
• Relationship field resolution by import key/slug
• Cleaner snapshot vs developer snapshot modes
• Better template fingerprinting
• Direct API push from AI/chat to WordPress
• Import package archive/history in WordPress
• Rollback support
• More visual preview UI
• Field-level diff preview
• Import validation against required fields
• Site-specific template slot aliases

WooCommerce Notes

The tested template site had a product CPT, but it did not appear to be a normal WooCommerce product setup because WooCommerce taxonomies like product_cat, product_tag, and product_type were not present.

WooCommerce should be tested separately on a Woo-enabled staging site.

Recommended WooCommerce test order:

1. Simple products
2. SKU/price/stock/status
3. Product categories/tags
4. Attributes
5. Featured image and gallery
6. Variable products
7. Variations

Final Summary

Marketing Sux Content Magic is a structured content deployment layer for AI-assisted agency workflows.

It lets humans and AI collaborate like this:

WordPress exports structure → AI writes mapped content → WordPress imports safely.

The plugin is especially useful for:

• ACF-heavy websites
• Elementor dynamic templates
• landing pages
• local SEO page builds
• service pages
• city pages
• CPT entries
• global content/options fields
• business info fields
• patch-style updates
• legacy ACF field sets

The plugin is not trying to replace strategy, writing review, SEO judgment, or human QA.

Its job is to make the final approved content easy to deploy without CSV mapping, manual copy/paste, or brittle import-plugin workflows.

Field Intent Mapping / Closest Functional Match

The Site Template JSON is the source of truth for exact field names, keys, and active site structure. However, agency writing instructions, formatting guides, and reusable ACF specs may not always use the exact same field names as a specific client site.

When the writing guide and live site template differ, AI should map by field intent, not by name alone.

Use this priority order:

1. Exact field name match
   Example: body_1_content → body_1_content
2. Exact field label match
   Example: “Body 1 Content” → field label “Body 1 Content”
3. Same tab/section + same field role
   Example: a field under “Hero” labeled “Main Heading” may serve the same role as hero_heading_h2
4. Same content type + formatting behavior
   Example: a WYSIWYG field intended for longform body copy may map to the Body 3 role even if named main_content, longform_content, or service_body
5. Same frontend/template purpose
   Example: a field used as the on-page H1 should receive the H1/focus keyword style instruction, even if its field name is banner_title, main_heading, or hero_title
6. Ask before guessing when confidence is low
   If two fields could reasonably serve the same purpose, AI should stop and ask the human which field to use.

Field Intent Beats Field Name

If an older site has a legacy field like:

"banner_title": {
  "label": "Banner Title",
  "type": "text"
}

…and the writing guide refers to:

"hero_pre_heading_h1"

AI should not assume they are different just because the names do not match. It should check:

• field label
• tab/section
• instructions
• field type
• frontend purpose
• nearby companion fields
• existing content snapshot values

If banner_title is the page’s visible H1, then apply the Hero Pre-Heading/H1 writing rule to banner_title.

Formatting Rules Follow the Field’s Functional Role

Formatting instructions should be transferred by role.

Examples:

• A field acting as Body 1 Content should get one paragraph plus optional bullets only. Do not add H2/H3 headings.
• A field acting as Body 2 Content should get one paragraph plus optional bullets only. Do not add H2/H3 headings.
• A field acting as Body 3 / Longform Content can include multiple H2/H3 blocks, paragraphs, bullets, and internal links.
• A field acting as FAQ Answer should be plain text only, even if the field technically allows HTML.
• A field acting as a textarea card description should usually be plain text / line breaks only.
• Image fields should be omitted unless intentionally updating or clearing images.

Mapping Confidence Labels

When mapping a reusable writing guide to a live site template, AI should classify each mapped field:

• Exact Match — same field name or obvious same label
• Strong Match — different name, same label/section/type/use
• Probable Match — similar role, but legacy naming or unclear frontend use
• Needs Human Confirmation — multiple possible targets or unclear purpose

For high-volume imports, AI should show a short mapping summary before generating the final import JSON when legacy fields are involved.

Example Mapping

Reusable writing guide says:

"hero_pre_heading_h1": "Main on-page H1"

Legacy site template has:

"banner_title": "Banner Title"

If the field is in the Hero/Banner section and appears to control the visible H1, map:

"banner_title": "Roof Replacement"

Do not invent hero_pre_heading_h1 if that field does not exist on the live site.