How do you migrate a Drupal site to Sanity, step by step?

How do you get content out of Drupal for a move to Sanity?

You get content out of Drupal 8.7 and later through core's JSON:API module, and out of Drupal 7 through added modules.

• Drupal 8.7 and later. JSON:API, a core application programming interface (API) since 8.7.0 (Drupal 8.7.0 release notes, October 2026), is "a zero-configuration required, opinionated" way to read a site's content, Drupal.org says. Its resources follow Drupal's entity types and bundles, so each content type exports as its own collection (Drupal.org, JSON:API module, October 2026).
• Drupal 7. Core has no JSON:API, so you install extra modules to get one (Sanity's Drupal guide, October 2026).

Which export tool fits your Drupal version compares the routes. Sanity Learn has no Drupal course (Sanity Learn, October 2026), though its WordPress course says many of its techniques transfer to HTML-based content management systems like Drupal (Sanity Learn, October 2026). For AI agents, Sanity's MCP (Model Context Protocol) server lists a guided Drupal path (Sanity blog, October 2026), and Sanity's migration skill has a Drupal guide covering "source-specific extraction routes" (Sanity agent toolkit, October 2026). Sanity calls that skill "agent-scaffolded, not fully automated" (Sanity blog, August releases, October 2026). This playbook assumes you've decided to leave Drupal; whether to upgrade to Drupal 11 or replatform is its own question. Our view of Drupal rests on its documentation and public sources.

How do Drupal content types and fields map to Sanity schema types?

Each Drupal content type becomes a Sanity document type, and each Drupal field becomes a field you define in code on that type, with a validation rule where Drupal had one. Sanity starts blank: "There are no content types setup with a clean installation" (Sanity's Drupal guide, October 2026). A list field's allowed values move to a string field's options.list of "predefined values" (Sanity Docs, String, October 2026).

How do Drupal entity references and taxonomy map to Sanity references?

Drupal entity references become Sanity references, and the import makes their order irrelevant: "During import, all references are automatically set to weak, then flipped to strong after all documents are in place" (Sanity Docs, Import data, October 2026). Sanity accepts any ID made of letters, numbers, hyphens and underscores, so an ID such as node-123 or term-45 keeps the Drupal entity ID and lets every rerun hit the same document. Drupal taxonomy terms can have hierarchies (Sanity's Drupal guide, October 2026), so each term becomes a document with a parent reference.

Two Drupal structures leave this mapping. Revisions stay behind in an archived Drupal database (Deploi's judgment), and Drupal translations get their own playbook because Drupal.org lists the translation support in core's JSON:API module, an application programming interface (API), as "Basic functionality" (Drupal.org, JSON:API module, October 2026).

What do Drupal HTML body fields, Paragraphs and Layout Builder become in Sanity?

Drupal HTML body fields become Portable Text, Paragraphs become arrays of object types, and Layout Builder overrides need a modeling decision before any script runs. Portable Text is Sanity's JSON-based format for rich text storage (Sanity's Drupal guide, October 2026); how Portable Text stores rich text explains it.

• HTML body fields. htmlToBlocks() from @portabletext/block-tools converts headings, lists and paragraphs by default, and images need custom rules (Sanity Learn, Converting HTML to Portable Text, October 2026). HTML tables have a target: the Portable Text Editor has built-in table editing from Studio v6.6.0, off by default, once you declare a table schema type (Sanity Docs, Configure the Portable Text Editor, October 2026).
• Paragraphs. The module lets editors pick predefined Paragraph types instead of one WYSIWYG (what you see is what you get) body field (Drupal.org, Paragraphs, October 2026). Each Paragraph type becomes an object type in an array, the way Sanity models a page builder (Sanity's Drupal guide, October 2026), and a nested Paragraphs field becomes an array inside that object (Deploi's judgment).
• Layout Builder. It can "override the default display on individual items such as nodes" (Drupal.org, Layout Builder, October 2026), so each overridden node carries its own layout. Decide per override: a page builder array, or the default template.

Pages built in Acquia Site Studio follow their own path to Sanity.

What happens to Drupal media, files and images in a move to Sanity?

Drupal media, files and images become Sanity image and file assets, uploaded by the import itself through the _sanityAsset property. In each NDJSON (newline-delimited JSON) line, _sanityAsset sits where an asset reference would go, prefixed image@ or file@, with an absolute file path or a public URL (Sanity Docs, Import data, October 2026). The import fails when an asset is unavailable unless you pass --allow-failing-assets, so check every Drupal file URL before the run and log the ones that 404.

• Alt text and captions. Copy them into fields on the Sanity image object, so they travel with every use (Deploi's judgment).
• Shared files. A Drupal media entity used on many nodes is one file. Sanity gives an uploaded image an ID derived from the image itself, so uploading the same image twice never creates a duplicate. Uploading through the JavaScript client also lets you record the Drupal media ID in the asset's source key, so a rerun can skip files already uploaded (Sanity Learn, Uploading assets efficiently, October 2026).
• Media Library. Sanity's organization-wide asset app is an add-on for certain Enterprise plans as of October 2026 (Sanity Docs, Media Library introduction; Sanity pricing). A Drupal move can use ordinary dataset assets instead, which need no add-on.

How do you keep Drupal URL aliases and redirects working after a move to Sanity?

Keep Drupal URLs by exporting each node's current URL alias into a Sanity slug, and each Redirect module entry into a redirect document your front end reads. Pathauto builds aliases from a pattern system "that uses tokens which the administrator can change" (Drupal.org, Pathauto, October 2026), so export the alias each node has today, not the pattern: nodes published under an older pattern can keep older aliases (Deploi's judgment).

The Redirect module lets editors "create manual redirects and maintain a canonical URL for all content" (Drupal.org, Redirect, October 2026). Each one becomes a redirect document with a source, a destination and a permanent flag, the model in Sanity's redirect guide (Sanity Docs, Managing redirects with Sanity, October 2026). That guide notes that in Drupal, redirects are "typically a plugin away", while a headless front end needs integration work to read them. Add Drupal's system paths, such as /node/123, as redirects too, because old links and feeds still use them (Deploi's judgment). Keeping search rankings through the move carries the full SEO (search engine optimization) checklist.

What replaces Drupal roles, Content Moderation, Views and modules like Webform and Search API?

Drupal's roles, moderation and modules, including Search API (a search application programming interface module), don't migrate. Each becomes a Sanity setting, a GROQ (Graph-Relational Object Queries) query in the front end, or a service. Drupal grants editor permissions "based on role and content type" (Sanity's Drupal guide, October 2026). Sanity's Growth plan has five fixed roles that span whole datasets (Contributor writes drafts "within all datasets"), so none limits an editor to one content type. Custom roles are Enterprise only as of October 2026 (Sanity Docs, Roles and permissions; Sanity pricing). Drupal's Content Moderation adds states beyond published and unpublished (Drupal.org, October 2026); Sanity Workflows is in early access (Sanity Docs; early access terms, October 2026).

Site search on Sanity compares the search options.

What is the step-by-step plan for a Drupal to Sanity migration?

A Drupal to Sanity migration runs in ten steps, and the import runs many times. It fails on any document ID that already exists, so reruns pass --replace with the same Drupal-derived IDs (Sanity Docs, October 2026).