Converting a Hard-Coded Drupal Landing Page to Paragraphs
A polished Twig page can become difficult to maintain when its copy and repeated components are embedded in templates or installation code. The presentation belongs in Twig; editorial values belong in Drupal entities.
Model stable sections and repeatable components
Use typed node fields for hero, profile, contact, and section headings. Use Paragraph types for repeatable experience roles, selected projects, and skill groups.
Migrate without losing the existing page
- Create and export field configuration.
- Create an idempotent content migration.
- Render the new node with a bundle-specific Twig template.
- Point the front page to an environment-independent alias.
- Keep legacy blocks temporarily as a rollback source.
Test the editorial experience
Verify that editors can add, duplicate, reorder, collapse, and remove Paragraph components. Confirm CKEditor formats long text fields and that unpublished test content can be safely created and removed.
The result
The site retains a purpose-built frontend while Drupal manages structured content, revisions, permissions, configuration exports, and reusable components.
Choose fields and Paragraphs for different reasons
Stable values that exist exactly once on the page are often clearer as normal node fields. Repeatable, reorderable groups of related values are where Paragraph components become more useful. Making every sentence a Paragraph creates unnecessary editorial complexity, while putting an entire page into one formatted-text field throws away useful structure.
The content model should reflect the decisions an editor needs to make, not the number of visual boxes in the current design.
Make the migration idempotent
A migration used during development may be executed repeatedly while the model is evolving. Use stable identifiers and detect existing destination content so another run updates or skips what is already present instead of creating a second portfolio page and another set of Paragraph revisions.
Export the field and Paragraph configuration separately so a new environment receives the content model before the migration attempts to create entities.
Preserve a clean theme contract
The final Twig template should receive structured fields and rendered Paragraph components rather than reconstructing the old hard-coded page in preprocess code. Presentation remains in the theme, editorial values remain in content, and Drupal's normal revision, translation, access, and caching systems can participate.
Key Takeaways
- Use ordinary fields for stable single values and Paragraphs for repeatable components.
- Make content migration safe to run more than once.
- Keep presentation in Twig and editorial values in entities.