Why Drupal content modeling with Paragraphs and Layout Builder needs a decision before the build
An editorial team that needs structured, editor-friendly pages should settle its page-building approach before the first content type is created. Paragraphs, Layout Builder and Drupal Canvas solve different problems, and the choice shapes content types, field permissions, the migration plan and how far content can be reused on other channels. Paragraphs models reusable blocks of structured fields inside a content entity. Layout Builder lets editors arrange sections and blocks on a page. Drupal Canvas, previously Experience Builder, is a visual page builder that the Drupal CMS page describes for marketers and content teams. Each one places layout, content and presentation in a different part of the model, so a team that picks one without a plan can end up rebuilding content types later.
This decision usually comes up in three situations: a new build, a redesign of an existing site, or a move away from free-form body fields that editors have used to paste HTML. Teams that are leaving a body field often discover that the content they need to reuse, such as a call to action, a stat block or a product teaser, is buried in markup. In each case the work is best scoped with content owners and editors before any theme work starts, because the content model determines what the theme has to render, which fields editors can edit, and which roles can change layout or only content.
Confirm the current status of each module against your target Drupal release before you commit. The Drupal CMS page on Drupal.org describes the status of Drupal Canvas and the recipes that ship with it, and the project pages for Paragraphs and Layout Builder on Drupal.org list supported core versions and maintenance status. Your Drupal version also sets which major versions and PHP levels apply, so check those requirements early, and ask your implementation partner to document the chosen approach in writing with the content owners who will sign off on it.
What Paragraphs, Layout Builder and Drupal Canvas each do
Drupal offers several ways to assemble structured pages, and each one sits at a different level of the content model. Paragraphs holds reusable blocks of content, Layout Builder arranges sections on a display, and Drupal Canvas is a visual builder described on the Drupal CMS page. Choosing between them starts with deciding which parts of a page belong to content and which belong to layout.
Content types and fields
Content types and their fields are the foundation under every page-building approach. Fields define what an editor enters, such as a title, body, image or reference, and they determine how that content can be reused in other channels like APIs, search or feeds. Model entities around what the content is, not how one page happens to look. Before choosing a builder, list the fields each content type needs and which ones must stay consistent across channels. Confirm which field types your chosen Drupal version and contributed modules support.
Paragraphs as reusable blocks
The Paragraphs module lets you add a field to a host entity, such as a node, that holds a set of reusable paragraph types. Each paragraph type has its own fields, so an editor can add a hero, a quote or a call to action in a defined order. Because paragraphs are entities stored inside a host, they can be reused and rendered consistently across templates. Check the paragraph type limits, nesting depth and translation behavior against the Drupal.org documentation for the version you run.
Layout Builder for section layouts
Layout Builder is part of Drupal core and lets site builders define sections and regions for a content type or view mode, then lets editors place blocks into those regions for a specific entity. It answers the question of where content sits on a page, rather than what the content is. Override behavior matters: a layout can be set as the default for all entities of a type or changed for one entity. Confirm how overrides, revisions and content moderation interact before editors rely on them.
Drupal Canvas as a visual builder
The Drupal CMS page describes Drupal Canvas, previously Experience Builder, as the visual page builder in the Drupal CMS distribution, built for marketers and content teams. It is a different product from the core modules and sits within a distribution rather than a standard core install. Treat it as a decision to evaluate against your existing content model, not a drop-in replacement for Paragraphs or Layout Builder. Confirm its current status, supported Drupal version and component model with Drupal.org before you commit a design to it.
Compatibility with your Drupal version
Paragraphs, Layout Builder and Drupal Canvas each depend on specific Drupal core and contributed module versions. Drupal 10 requires PHP 8.1 or later and Drupal 11 requires PHP 8.3 or later, so a PHP upgrade can be part of the same decision. Check each module's release notes and supported core versions on its Drupal.org project page before choosing. Plan the upgrade path for paragraph types and layouts, since changes to field storage can affect existing content.
Which option fits which page type and team
This table compares Paragraphs, Layout Builder and Drupal Canvas across the decisions that shape a content model: who builds layouts, multi-channel reuse, design governance, preview and versioning, and translation and permissions. Read each row against your own team and channels, and treat any cell marked for verification as a question to confirm against current module documentation before you commit.
| Decision | Paragraphs | Layout Builder | Drupal Canvas |
|---|---|---|---|
| Who builds layouts | Editors compose from predefined paragraph types; developers define the types and their templates | Editors rearrange blocks per node or template; developers provide the blocks and sections | Marketers assemble pages visually from components; developers build and expose components (verify current maturity) |
| Same block on web, app and email | Strong fit: paragraphs are fields, so headless APIs and other templates can read them (verify JSON:API output) | Weak fit: layout lives in presentation config, so other channels usually need a separate rendering path | Limited for now: built for page rendering on Drupal; confirm how components reach non-web outputs |
| Design change governance | Changes to paragraph templates are code and theme work, reviewed through normal releases | Section and block layouts can drift per page unless templates are locked down with configuration | Components and page templates are managed through the builder; confirm how changes are reviewed and promoted between environments |
| Preview and versioning | Preview depends on the node form and theme; revisions track paragraph field changes with the node | Preview is per node in the layout interface; layout overrides are stored separately from content revisions (verify with Content Moderation) | Visual preview is the core feature; confirm how drafts combine with Content Moderation and Workspaces |
| Translation | Paragraph fields can be translatable per field; plan which paragraph types carry translated text | Layout overrides per translation can multiply maintenance; keep block content translatable and layouts shared | Confirm translation behavior for built components and page content before committing |
| Permissions | Controlled through entity and field permissions on the parent node and each paragraph type | Controlled through layout and block permissions; editors can change layouts they can access | Controlled through builder and component permissions; confirm roles against your editorial model |
| Fits when | Structured landing pages, reusable content blocks and content that must reach several channels | Template-level page layouts with limited editor control and a small set of block types | Marketing-led teams that need visual page building and accept a newer, faster-moving tool |
| Wrong tool when | Editors need free-form page design, or content is a single long text body | Content must be reused outside the website or layouts vary heavily per page | Regulated content needs strict versioning, or the site must run on an older Drupal core release |
How the model changes by team, channel and content type
Marketing teams usually need to assemble landing pages quickly, so the model leans toward Paragraphs or Layout Builder with a small set of well-named content types. Editors choose the components and their order, and the page is the unit of change. The governance rule is that editors may add and reorder components on pages but may not create new component types. Each paragraph type should map to one job, such as hero, feature grid or call to action, so that a page can be rebuilt without rewriting its text.
- Shared components: brand blocks such as the hero, testimonial and call to action, defined once with fixed fields and used across pages.
- Page-specific content: headlines, campaign copy and one-off images entered in the paragraph instance, not in a shared library.
- Layout control: Layout Builder sections give more visual freedom, while Paragraphs keep the component list in the content record, which is easier to query.
- Trade-off: more freedom means more variation in tone and accessibility, so set guardrails on heading levels and image alt text.
- Drupal CMS: if the team wants a visual builder with recipes, check the Drupal CMS page and confirm how it fits your existing content model.
Before committing, check which components marketing will reuse across campaigns and which will be rebuilt for each launch.
Publishers usually need the article body and metadata to stay consistent across the website, apps, newsletters and syndication. The model favors fixed content types with typed fields, and paragraphs are used only where a repeatable block is genuinely needed, such as a pull quote or embedded data. Layout is owned by the templates, not by editors, so layout decisions do not leak into the content record. Governance is tighter: editors fill fields and choose from approved blocks, and the template team controls the structure.
- Shared components: bylines, related-story lists, figures with captions and standard callouts, each with fixed fields.
- Page-specific content: the story body, dek, and editor-chosen images, which travel with the article to every channel.
- Layout control: templates per channel rendered from the same fields, so a change to a field appears everywhere it is used.
- Trade-off: strict templates reduce variation but slow down one-off features, which need a template change or a new block.
- Channel rules: keep channel-specific text in fields flagged for that channel, not in the body, so the body stays reusable.
Before committing, list every channel that will read the content and confirm which fields each one needs.
Across several sites or languages, the main risk is duplicating the model until each site drifts. The model should define shared content types and components once in a single configuration, then allow site-level variation only where it is intended, such as regional offers or local legal text. For multilingual content, each paragraph and field must be translatable by design, and layout choices must survive translation. Governance covers who may change shared components, who may override them locally and how changes roll out.
- Shared components: the same paragraph and content type definitions across sites, managed in one configuration so changes apply consistently.
- Page-specific content: regional copy, local contacts and translated text, stored per language or per site as the design requires.
- Translation rules: mark fields as translatable or not when the model is designed, since changing this later affects existing content.
- Trade-off: one shared model keeps governance simple but limits per-site experiments, so agree on an override process up front.
- Multisite choice: the Domain suite and core multisite suit different estates, so confirm the choice against the Drupal core release schedule for version planning.
Before committing, confirm which languages and sites need different content, not just different translations.
How the modeling work runs from content audit to editor sign-off
The sequence turns an inventory of existing pages into a content model that editors can use, reuse across channels and sign off before build work starts. Each stage closes with a named artifact so the client knows exactly what has been approved.
Audit content and inventory existing pages
The team reviews current pages, templates, content types and the editorial tasks behind them, with content owners and at least one editor from each team that publishes. The output is a page inventory listing each page pattern, its fields, its owners and the places where editors currently work around the templates. The client confirms the inventory is complete before modeling starts, because any page type missing here is likely to be built as an exception later.
Define channel and reuse requirements
Work with product and channel owners to list every place the content must appear, such as the main site, a mobile app, email, search results or a partner feed, and which parts of each page must be reusable. The output is a requirements document that separates shared content (for example, a product summary or a legal notice) from page layout. Ask each owner to confirm which channels are live now and which are planned, so the model does not depend on a channel that may not exist.
Select the layout option per content type
For each content type, the team compares Paragraphs for structured reusable sections, Layout Builder for editor-controlled arrangement within a fixed content type, and Drupal Canvas for visual page building where the current version fits the team's needs. The output is a decision record per content type that states the chosen option, the reason and the known limits. Confirm the current status and supported features of each option in your Drupal version before the decision is final, because these modules change between releases.
Design content types and paragraph types
The team turns the approved decisions into a model: content types, paragraph types, fields, required values, reference rules and display modes, with a short description of how each one is reused. The output is an approved model diagram and a list of paragraph types with their fields, limits and the channels that read each one. Content owners sign off on this model before any development begins, since changing fields after templates and migrations are built is costly.
Map permissions and editorial workflow
The team maps which roles can create, edit, reuse and publish each content type and paragraph type, and where Content Moderation states apply. The output is a permissions matrix and a workflow diagram showing who approves what and which states a page passes through. Security and content owners review the matrix together, and the client confirms it matches its governance rules before the prototype is built.
Prototype with real editor tasks
Editors use a working prototype on the agreed model to complete tasks drawn from the inventory, such as building a landing page from reusable sections or updating a shared notice across pages. The output is a short log of tasks attempted, where editors stalled and the changes agreed in response. The prototype is accepted only when the common tasks can be completed without developer help, and the client records that acceptance in writing.
Build components and templates
Developers build the approved paragraph types, layout configuration, templates and preprocessing for each channel, using custom modules where core and contributed options do not cover a need. The output is a deployed build in the client's environment with a list of components and their template mappings. Each component is checked against the model diagram, and any deviation is reported back to the content owners before it is accepted.
Train editors and run acceptance tests
The team runs training sessions for editors and reviewers and then executes acceptance tests written from the inventory and the permissions matrix. The output is a signed acceptance test report, training materials and a list of open issues with owners. Sign-off from the content owners closes the work, and any issues left open should be agreed as a scheduled backlog rather than left unassigned.
What drives effort and how to keep it down
This table lists the factors that change the size of a Paragraphs and Layout Builder project and the controls that keep each one contained. Read each row as a question to answer before quoting, since the first column names the driver and the second and third explain its effect and its containment. The main takeaway is that the model, component library and version target should be settled before any migration or page build begins.
| Driver | How it changes the work | How to keep it contained |
|---|---|---|
| Content types and paragraph types | Each new content type adds fields, view modes, permissions and templates, and each paragraph type adds a component an editor and a themer must both understand. | Agree a component library early, merge overlapping paragraph types, and sign off the list before build starts. |
| Existing pages to migrate | Legacy pages rarely map cleanly to paragraphs, so each source layout needs a mapping rule, a transform and a review pass. | Migrate by content type with a sample set first, and set a cut-off for which legacy pages are rebuilt by hand. |
| Channels consuming the model | A model read by a website, an app or an API needs stable field names, clear text formats and output that does not depend on one theme. | List every channel at discovery, decide which ones consume paragraphs directly, and test one non-theme consumer early. |
| Translation requirements | Each translatable field and paragraph multiplies review work, and layout changes in one language must be mirrored in the others. | Decide which fields are translatable before modeling, and keep layout-only paragraphs language-neutral where possible. |
| Editorial roles and approval flows | Editors need permissions for building pages, and approval steps add states that the layout and workflow configuration must respect. | Define roles and the approval path with editors in the same workshop as the model, and test them with real drafts. |
| Layout Builder use per node | Per-node layouts are hard to govern, reuse and migrate, and they add overrides that must be reviewed when templates change. | Limit per-node layouts to named exceptions and keep shared layouts in configuration. |
| Drupal version target | Paragraphs and Layout Builder must be checked against the chosen major version, and Drupal 12 is scheduled for the week of December 7, 2026, per the core release schedule, so a target that spans that date needs an upgrade check. | Confirm the module versions for the target release, run upgrade readiness checks on the model, and avoid custom code that depends on internals. |
| Model freeze before migration | Changes made during migration force re-runs of mappings and re-review of migrated content, which compounds with every other driver. | Freeze the content model and component library before migration, and route later changes through a documented change process. |
Moving existing pages into a paragraph or layout model
Migrating legacy body fields into structured components is usually the largest hidden cost of a paragraph or layout model. A classic body field holds HTML that editors have shaped over years, often with inline styles, embedded iframes, pasted tables and media tags that point at files which may have moved. Each of those patterns has to be mapped to a field on a paragraph type, a block in a Layout Builder section, or a media reference, and the mapping rules are rarely as tidy as the content model diagram suggests. Plan a discovery pass that samples real pages from every content type and section, counts the distinct markup patterns, and records which ones editors actually depend on. The number of patterns found in that pass, not the number of content types, is the best early indicator of effort. Ask any partner to show how they will handle unmatched markup, such as a fallback paragraph type or a report of pages that need manual review.
Decide page by page whether content is rebuilt, migrated as-is into a single rich text field, or archived. Rebuilding is worth the effort for landing pages, campaign pages and high-traffic guides that will be reused in new layouts. Archiving or leaving static copy is often the better choice for old announcements, event pages and press releases that nobody edits. Make that decision with the content owners, not only the developers, and record it in a migration inventory with an owner and a disposition for each section. Check URL aliases before any cutover: every alias that ranks, is linked from outside, or is referenced in forms or email should either be carried over exactly or redirected. Confirm also whether editorial history, revisions, translations and authorship must be kept, since some migration routes preserve revisions poorly and some content owners need them for audit.
If the source is Drupal 6 or 7, the migration path is different in kind. The Drupal.org documentation on upgrading from Drupal 6 or 7 to Drupal 8 and newer explains that these sites cannot simply be updated in place. They are migrated into a new site using the core Migrate, Migrate Drupal and Migrate Drupal UI modules or with Drush, and themes must be rebuilt because they cannot be migrated. That means the paragraph and Layout Builder mapping above must be designed alongside the new theme, and the mapping work cannot be treated as a content import task. Confirm with the team which current Drupal version the target will run on, because that choice sets the PHP and core requirements the new site must meet.
How the content model connects to the rest of the platform
A content model is only as useful as the systems that read it. Each connection below asks something specific of the fields, paragraph types and entity structure you define now, so decide them before the build rather than during the theming or migration phase.
Theme and component library
Paragraph types and Layout Builder sections are rendered by your theme, so each paragraph type needs a stable machine name, a defined field set and a matching component or template. Keep field names semantic rather than presentational, so a redesign does not force a data change. Confirm with your theme team which template system they will use and whether it supports the render arrays your paragraph types need. Read the core theming guidance on Drupal.org before locking field names.
Search index field mapping
Search API reads the fields you expose on each bundle, and it cannot index what the model does not store as a field. Nested paragraphs and layout sections need an explicit decision about which text, taxonomy references and images feed the index. Flatten searchable content into predictable fields where you can, and record which field feeds which facet. Confirm that your chosen search backend and module versions support the field types you plan to index.
Translation workflows
Translation depends on whether a paragraph is translatable and whether its fields are set per language. Decide early which bundles carry translatable text, which carry shared media or configuration, and which should never be duplicated. A model that mixes these in one paragraph type will make translation jobs hard to scope. Confirm translation module compatibility for your version before you plan review steps.
Editorial moderation and workflows
Content Moderation and Workspaces act on whole entities, so the state of a page depends on the state of every paragraph it embeds. Decide whether paragraphs are independently publishable or only move with their parent page. This choice shapes review steps, revisions and the permissions editors need. Read the editorial workflow page in this series before designing transitions.
JSON:API and headless front ends
Decoupled front ends read the model through JSON:API, which exposes paragraphs as nested resources with their own identifiers. Field names, entity references and image styles become part of your public contract, so changes need versioning discipline. Decide whether paragraphs are fetched inline or as separate resources, and test payload size on real pages. Read the headless Drupal page before you publish a schema.
Identity and editor permissions
Paragraph and layout permissions are separate from node permissions, so an editor who can edit a page may still be unable to add a specific paragraph type. Map roles to paragraph types, layout sections and text formats deliberately, and test them with each identity source you connect. Single sign-on changes how roles are assigned but not what they allow. Confirm how your identity module maps groups to Drupal roles before you define the permission matrix.
What buyers ask before hiring a partner for Drupal content modeling
How much does a Paragraphs or Layout Builder implementation cost?
The cost depends on the written scope, not on the module name. Paragraphs and Layout Builder are both free, open-source Drupal contributed or core components, so the fees you pay are for people: discovery, content type and paragraph design, theme component work, editor training and testing. The main drivers are the number of content types and paragraph types, how many channels the model must serve, how much custom field logic or validation is needed, and how many editorial roles must be supported. Ask for a quote that lists each deliverable, what is one-time build effort and what is ongoing support, and which items are excluded. DeployOpen does not publish a price list, so the quote follows from the agreed scope.
How long does the content modeling phase take?
The schedule is set by how many content decisions must be made and how quickly stakeholders can make them. Modeling usually runs in stages: a content inventory, a review of existing templates, a proposed model, editor walkthroughs, and a build of the agreed types. Schedule drivers include the number of distinct page patterns, the count of stakeholders who must approve a model, whether legacy content must be mapped, and whether the brand design system already has components for each pattern. Ask the partner to show the phases, the review points and the sign-off owners in the written plan, and to state what happens if a review is delayed.
What must our team provide before modeling starts?
Plan to supply four things. First, a content inventory covering existing page types, their fields, volumes and owners, even if it is a spreadsheet. Second, named editors who can attend workshops and test prototypes during the build. Third, brand components, style guides and design files that define the page patterns your marketing team uses. Fourth, sign-off owners with authority over content structure, accessibility and publishing rules, so decisions are not reopened late. Confirm in the scope which of these are your responsibility, how many review cycles are included, and who will approve the final model.
Can our internal team build the content model without a partner?
Yes, many teams do, especially when they already run Drupal and have developers familiar with content types, field configuration and theme templates. A partner adds value when the model must serve several channels, when editors and developers need an outside reviewer for structure decisions, or when the team has no spare capacity. The decision usually comes down to skills, time and risk tolerance. Ask yourself whether your team can maintain the model after launch, write the tests that catch regressions, and document decisions for future upgrades. A written scope lets you compare doing it internally against a partner's deliverables side by side.
Is Drupal Canvas ready for our use case?
Drupal Canvas, previously called Experience Builder, is a visual page builder included in Drupal CMS, which is a distribution built on Drupal core. Whether it fits depends on your editors' needs, your governance rules and the maturity you require for your channels. Check whether the features you need are available in the version you will run, whether your component library can be exposed to editors safely, and how pages built in Canvas will be exported, reviewed and upgraded. Layout Builder and Paragraphs remain established options with their own trade-offs. A written assessment should test Canvas against your real pages before you commit the model to it.
How does the content model affect future Drupal upgrades?
Upgrade cost is shaped mostly by how much custom code and configuration sit on top of the model. Heavy custom field logic, nested paragraphs with complex dependencies, and theme templates that rely on undocumented field names all increase the work when core or contributed modules change. Drupal core moves to new major versions roughly every three years, and Drupal 10 reaches end of life on December 9, 2026, so plan the model with that calendar in mind. Ask for the model to be documented, covered by automated tests where practical, and kept in configuration management so upgrades can be checked in a staging environment.
What happens to the model when new channels are added?
A well-designed model separates the content itself from the presentation, so a new channel reads the same fields and renders them differently. Problems appear when content types were designed around one page layout, such as a homepage template with fixed positions, because another channel then needs duplicated fields. Ask how the model will expose content to APIs or other front ends, how fields will be named and documented, and how editors will know which fields apply to which channel. Your written scope should state which channels are in the first release and how adding a channel is handled as a later change.
How DeployOpen works on this
DeployOpen plans and builds Drupal content models as part of a self-hosted platform inside your own infrastructure. We start from the content your teams publish and the channels it must reach, then agree the Paragraphs, Layout Builder and content type design in writing before build work starts.
How we scope
- The written scope lists each content type, paragraph type and layout region to be built, with the editors who will use them.
- Scope names which pages use Paragraphs, which use Layout Builder and which stay as fixed templates, with reasons for each choice.
- Engagements are fixed-scope, so scope, deliverables and timelines are agreed in writing before work starts, and a quote follows from that scope.
How we build
- Content types and fields are built as configuration, so the model can be exported, reviewed and deployed across environments.
- Paragraph types are kept free of presentation logic, so the same content can feed a theme, an API or another channel.
- Each layout and paragraph type is tested with real editor workflows, including revisions, translations and content moderation where in scope.
How we hand over
- Handover includes the content model documentation, a field and bundle inventory, and the configuration export used to rebuild the site.
- Editors receive guidance on when to add a paragraph, when to change a layout and when to request a new content type.
- Upgrade notes cover the contributed modules involved, so future Drupal core and module upgrades can be planned against a known model.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, so the model keeps working through Drupal releases.
- Retainer work can cover adding paragraph types, reviewing new editor requests and checking the model before each planned upgrade.
- Ask any partner to confirm which contributed module versions and Drupal core versions they will test against during the engagement.
