Skip to content

document CMS rendering workflow and improve feedback for unmapped CMS elements #2329

@mkucmus

Description

Improve CMS Rendering DX (Docs + Debug Feedback)

Summary

In a headless setup, there is a natural gap between what the API returns and how the frontend renders CMS data. Currently this is not clearly explained, which leads to assumptions that CMS blocks or elements should auto‑render.

Problem

The current documentation and developer feedback are not clear enough about:

  • what the API returns
  • what is rendered automatically
  • what requires manual frontend mapping
  • how to debug missing CMS elements

Proposed Improvements

1. Documentation

Add clearer docs and examples describing:

  • the CMS rendering workflow
  • how CMS elements/slots are mapped in the frontend
  • what is handled by default vs what requires implementation

2. Debug Feedback

Provide better developer signals during development:

  • console warnings for unmapped CMS elements
  • hints about missing slot/element implementations

3. Development Placeholders

Render visible placeholders in dev mode when a CMS element exists in data but is not implemented in the frontend.

Outcome

Clearer expectations around CMS rendering in headless setups and reduced developer confusion/support load.

Metadata

Metadata

Labels

cms-basedocumentationImprovements or additions to documentation
No fields configured for Improvement.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions