Toggle DatoCMS block labels on preview mode by anareyna · Pull Request #309 · voorhoede/head-start

anareyna · 2026-02-05T10:23:45Z

Changes

Adds visual block labels in preview mode that allow users to quickly identify and edit blocks in DatoCMS.

What changed

Block labels: Block names appear as overlays in preview mode (toggleable via "show blocks" button)
Clickable labels: Clicking a block label opens the block's focus field in DatoCMS editor
Field path detection: Automatically detects the primary editable field for each block type
Nested block support: Correctly handles nested blocks (e.g., blocks inside GroupingBlock items)

Technical details

Added block-debug-utils.ts for field path building and API key conversion
Enhanced download-item-types.ts to detect focus fields (rich text, media, JSON, links, etc.)
Updated Blocks.astro to render debug labels with correct field paths
Updated PreviewMode.client.ts to handle label positioning, hover effects, and edit link generation
Added hideDebugLabels prop to skip labels in specific contexts (PagePartialBlock, TextBlock inline blocks)

Usage

Block labels appear automatically in preview mode when:

Preview mode is active
PreviewModeSubscription receives a record prop
"show blocks" button is toggled on

Labels are hidden for:

PagePartialBlock children (wrong record context)
TextBlock inline blocks (embedded in rich text)

Documentation

Updated docs/preview-mode.md https://github.com/voorhoede/head-start/blob/feat/show-blocks/docs/preview-mode.md#block-field-path-detection

How to test

Click "show blocks" button in preview bar
Verify block labels appear as overlays
Hover over blocks to see highlight effect
Click a block label to verify it opens the correct field in DatoCMS
Test nested blocks (e.g., blocks inside GroupingBlock)
Verify labels are hidden for PagePartialBlock children and TextBlock inline blocks

Test in other head-start based projects:

Checklist

I have performed a self-review of my own code
I have made sure that my PR is easy to review (not too big, includes comments)
I have made updated relevant documentation files (in project README, docs/, etc)
~~ I have added a decision log entry if the change affects the architecture or changes a significant technology~~
I have notified a reviewer

… item type IDs and generate model API keys

…ality. Updated documentation

…o go to, no fallback. Update docs

…ough data

…ieldPath assignment

cloudflare-workers-and-pages · 2026-02-05T10:24:44Z

Deploying head-start with Cloudflare Pages

Latest commit:	`d636d75`
Status:	✅ Deploy successful!
Preview URL:	https://a76bfebc.head-start.pages.dev
Branch Preview URL:	https://feat-show-blocks.head-start.pages.dev

View logs

jbmoelker

Really nice PR @anareyna! Thanks for the elaborate PR body (don't forget to check the boxes at the bottom ;)). Really great feature to be able to showcase during sales as well :). I made some suggestions. I would approve already except for one thing which is about possible nested anchors. I suggested a workaround there. An alternative could be not wrapping but using adjacent elements after the blocks that lay over their blocks.

jbmoelker · 2026-02-05T12:21:24Z

docs/preview-mode.md

+
+When clicking on a block label in preview mode, the system automatically generates a field path to focus the correct field in DatoCMS. Block labels are only clickable when `PreviewModeSubscription` receives a `record` prop (see above). This is done by detecting the "focus field" for each block type.
+
+### How it works


I love the effort you put into the docs ❤️. Maybe nice to reference why this works on the DatoCMS site by referencing their content link feature?

jbmoelker · 2026-02-05T12:23:49Z

scripts/download-item-types.ts

-});
+dotenv.config({ allowEmptyValues: Boolean(process.env.CI) });
+
+const FILE_PATH = './src/lib/datocms/itemTypes.json';


We don't use all uppercase const values elsewhere in the code base (other than for env variables). So I wouldn't start here. Just filePath etc.

jbmoelker · 2026-02-05T12:24:57Z

scripts/download-item-types.ts

-    .split(/[_-]/)
+function convertApiKeyToTypename(apiKey: string): string {
+  const words = apiKey.split(/[_-]/);
+  const pascalCase = words


https://www.npmjs.com/package/change-case ? or does DatoCMS maybe expose a method for this in general? I imagine they do the same thing in their packages.

if not provided I'd go with https://github.com/unjs/scule/
unjs packages are well maintained in general

jbmoelker · 2026-02-05T12:29:02Z

scripts/download-item-types.ts

+}
+
+// Run async work with a small concurrency cap to avoid spiking the api
+async function processItemsConcurrently<T>(


I'm okay with these methods, but always find them a bit hard to read. So maybe easier to use helper packages.
Use async parallelLimit? https://www.npmjs.com/package/async

jbmoelker · 2026-02-05T12:30:22Z

src/blocks/Blocks.astro

 import VideoBlock from './VideoBlock/VideoBlock.astro';
 import VideoEmbedBlock from './VideoEmbedBlock/VideoEmbedBlock.astro';
 import GroupingBlock from './GroupingBlock/GroupingBlock.astro';
+import { getDebugPaths } from './block-debug-utils';


I'm not sure if Debug is the best word. Is it Preview or Edit(or)?

makes sense, renamed debug prefixes and attributes to editor

jbmoelker · 2026-02-05T12:39:02Z

src/components/PreviewMode/PreviewMode.astro

    <div class="preview-mode-actions">
      {/* eslint-disable-next-line astro/jsx-a11y/anchor-is-valid */}
-      <a data-edit-record target="_blank" rel="noreferrer noopener">edit in CMS</a>
+      <a data-debug-edit-record target="_blank" rel="noreferrer noopener">edit in CMS</a>


There are now so many options in the preview bar that it no longer fits on smaller screens. So I think we need some responsive layouting here:

jbmoelker · 2026-02-05T12:40:49Z

src/components/PreviewMode/PreviewMode.astro

 }

-a[data-edit-record]:not([href]) {
+a[data-debug-edit-record]:not([href]) {


I'm wondering if we should hide the other labels when one has focus. Now I tried out some pages that have a nested or overlapping blocks and my highlighted block contents are still not entirely visible as other labels are over it.

jbmoelker · 2026-02-05T12:42:49Z

src/components/PreviewMode/PreviewMode.astro

+}
+:global([data-debug-blocks-visible="true"]) {
+  --block-label-z-index: 9999;
+  --block-label-color: #ff593d;


We've managed to only use primary colours up until now. So maybe use blue, similar to the Vercel content link?

jbmoelker · 2026-02-05T12:44:24Z

src/components/PreviewMode/PreviewMode.client.ts

+    }
+  }
+
+  #buildRecordEditUrl(itemTypeId: string, recordId: string) {


Does this belong here or in lib/datocms or block-debug-utils?

I'd keep it here since it uses these other instances (#datocmsProject, #datocmsEnvironment) and is only called in this class. We can extract it if it's ever needed elsewhere.

jbmoelker · 2026-02-05T12:45:18Z

src/components/PreviewMode/PreviewMode.client.ts

+    return `https://${this.#datocmsProject}.admin.datocms.com/environments/${this.#datocmsEnvironment}/editor/item_types/${itemTypeId}/items/${recordId}`;
+  }
+
+  #applyBlockEditLinks(itemTypeId: string) {


If we use clickable divs instead of anchors, this only needs to be executed on click.

I would also consider adding examples of these paths to a comment on this functions to make it easier to understand what goes in and out.

anareyna · 2026-02-06T12:56:29Z

Really nice PR @anareyna! Thanks for the elaborate PR body (don't forget to check the boxes at the bottom ;)). Really great feature to be able to showcase during sales as well :). I made some suggestions. I would approve already except for one thing which is about possible nested anchors. I suggested a workaround there. An alternative could be not wrapping but using adjacent elements after the blocks that lay over their blocks.

thanks!, not sure if I'm missing something about nesting anchors but currently the <a class="block-name-label"> is a sibling of the <Block>, not a wrapper. They're both inside a <> fragment. So there's no nesting of anchors here. @jbmoelker

jbmoelker

sorry, no nested anchors. so approved. the rest are just suggestions for minor improvements.

…nstead of debug...

anareyna added 30 commits January 13, 2026 14:12

Add 'feat/edit-page' to previewBranches in config/preview.ts

8495f05

Preview bar - Edit inDatoCMS button feature - Add scripts to download…

b6c8358

… item type IDs and generate model API keys

Docs for "Edit in DatoCMS" link feature

c445be8

Move files to more generic folder and rename them for more clarity

54d69c6

Refactor fallback url

1444aac

Simplified project name extraction and removed unused api token

c9fb8eb

Refactor Edit in DatoCMS link feature to improve clarity and function…

c8a1d5d

…ality. Updated documentation

Refactor Edit in datocms button to only display when there's a link t…

cecdb8d

…o go to, no fallback. Update docs

Reset file

9b17424

Reset formatting changes

66b1c59

Update docs

3b36ca0

Update item types file naming and adjust docs

9b823e4

Fix build

74cb0f5

Improve api token error handling

4a3239c

Clean up fallback logic

9b6cf09

clarify documentation

34256b8

consume data from preview mode, keep just one scrip file

3970519

remove EditInDatoCms component and link generation logic

2b8103c

remove unused itemTypes.ts file

3633a5f

Remove unused type and simplify component

919a3b8

Remove itemTypes.json file and update .gitignore

59e9c53

Remove whitespace

d723155

Update docs

edc8746

remove unused datocmsRecord from 404 page

ae7813f

Avoid ci error for types download logic when api token is missing

719f405

Remove unused buildEditorLink logic

1380ef7

Reset formatting

7820dc4

remove invalid href from edit link and hide link when we dont have en…

da83770

…ough data

Clean up whitespace in PreviewMode.client.ts

292e835

add edit page support 404 page

5e15b3e

anareyna added 10 commits February 3, 2026 13:59

Reset file changes

78b0f12

Add actual block names to item types

72df6a3

Remove layout display from block name

f3d27c0

Refactor PreviewMode class to separate cms debug tools

7f850b9

Docs clarify focus field selection process and nested block handling

f316356

Improve attribute names to make it clear they are for debug purposes

51edaba

Refactor block name label styles

6f2002f

Clean up blocks.astro file and add utils file to reduce clutter

06042e7

Create emoty itemTypes.json file if no token to avoid error

92d629e

Improve debug field path in Blocks and GroupingBlock. Simplify debugF…

29bd62a

…ieldPath assignment

anareyna marked this pull request as ready for review February 5, 2026 10:37

jbmoelker requested changes Feb 5, 2026

View reviewed changes

anareyna added 4 commits February 6, 2026 13:04

Improve docs on block label functionality

325b142

Camelcase variable names in download-item-types.ts

d83569d

Add scule dependency and update related functions for case conversion

f965bab

Refactor async processing in download-item-types.ts

cf1fcd9

jbmoelker approved these changes Feb 9, 2026

View reviewed changes

anareyna added 6 commits February 10, 2026 10:20

change label color to blue, adjust other styles

1246163

Add relevant examples and docs for functions in script

41c3a8d

Enhance block label styles and add external icon to block names

2c68b48

Update PreviewMode styles to improved responsive styles

2f50cd0

Set icon height

504bbe1

Refactor variable names to use editorFieldPath and hideEditorLabels i…

d636d75

…nstead of debug...

anareyna changed the title ~~Feat/show blocks~~ Toggle DatoCMS block labels on preview mode Feb 10, 2026

jbmoelker self-requested a review February 10, 2026 13:04

jbmoelker approved these changes Feb 10, 2026

View reviewed changes

jbmoelker merged commit de6c5e1 into main Feb 10, 2026
5 checks passed

jbmoelker deleted the feat/show-blocks branch February 10, 2026 13:04


		When clicking on a block label in preview mode, the system automatically generates a field path to focus the correct field in DatoCMS. Block labels are only clickable when `PreviewModeSubscription` receives a `record` prop (see above). This is done by detecting the "focus field" for each block type.

		### How it works

Conversation

anareyna commented Feb 5, 2026 • edited by jbmoelker Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

What changed

Technical details

Usage

Documentation

How to test

Checklist

Uh oh!

cloudflare-workers-and-pages bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying head-start with Cloudflare Pages

Uh oh!

jbmoelker left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anareyna commented Feb 6, 2026

Uh oh!

jbmoelker left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

anareyna commented Feb 5, 2026 •

edited by jbmoelker

Loading

cloudflare-workers-and-pages bot commented Feb 5, 2026 •

edited

Loading