Edit page link for preview bar (#306)

# Changes
Adds an “edit page” link to the preview bar that links to the current
page record editor (when we have id + __typename), so editors can jump
from a preview page straight into the CMS record.

## Documentation link
See:
https://github.com/voorhoede/head-start/blob/feat/edit-page/docs/preview-mode.md#edit-in-datocms-link

# How to test

<img width="1434" height="434" alt="SCR-20260120-nsbz"
src="https://github.com/user-attachments/assets/8dc06968-6f97-4f93-8fea-c7804d2d8c3a"
/>


# 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

<!-- Please strike through and check off all items that do not apply
(rather than removing them) -->

Author: anareyna

.gitignore

@@ -18,6 +18,7 @@ node_modules/
 reports/
 src/assets/icon-sprite.svg
 src/assets/icon-sprite.ts
+src/lib/datocms/itemTypes.json
 src/lib/datocms/types.ts
 src/lib/i18n/messages.json
 src/lib/i18n/types.ts

config/preview.ts

@@ -3,6 +3,7 @@ import { execSync } from 'node:child_process';
 export const previewBranches = [
   'preview',
   'feat/pages-content-collection',
+  'feat/edit-page'
 ];
 
 function getGitBranch() {

docs/preview-mode.md

@@ -6,6 +6,12 @@
 
 To enable preview mode for a git branch, you must add it to [`config/preview.ts`](../config/preview.ts). Preview branches will deploy as `output: 'server'` rather than `output: 'hybrid'`, ignoring all `getStaticPaths()` and always rendering the page during run-time. The `preview` branch is configured as one of the preview branches and is automatically kept in sync with the `main` branch, so it can be used as preview equivalent, for example from the CMS.
 
+> [!TIP]
+> To enable preview mode during local development:
+> - Make sure your current git branch is included in [`config/preview.ts`](../config/preview.ts).
+> - Set `HEAD_START_PREVIEW_SECRET` and `DATOCMS_READONLY_API_TOKEN` in your local `.env`.
+> - Enter preview mode via `/api/preview/enter/?secret=...` (or the preview login form).
+
 To protect a part of the page that must only be available in preview mode, you can wrap it in the `PreviewModeProvider`, as is done in the [`Default.astro` layout](../src/layouts/Default.astro):
 
 ```astro
@@ -58,10 +64,63 @@ const variables = { locale, slug };
 const { page } = await datocmsRequest<PageQuery>({ query, variables });
 ---
 
-<PreviewModeSubscription query={ query } variables={ variables }  />
+<PreviewModeSubscription
+  query={query}
+  variables={variables}
+  record={{ type: page.__typename, id: page.id }}
+/>
 <h1>{page.title}</h1>
 ```
 
+The `record` prop is used to generate the "edit in CMS" link in the preview bar.
+
 ## Preview mode bar
 
 When in preview mode a bar in the user interface displays the status of the connection with the CMS, along with a link to exit preview mode. Depending on the layout of your project, you may want to move the preview mode bar to another position, for example if your project has a sticky header.
+
+## Edit in CMS link
+
+In preview mode, the preview bar shows an **"edit in CMS"** link that opens the record in DatoCMS.
+
+### How it works
+
+The link is automatically generated from the `record` prop passed to `PreviewModeSubscription`. The URL is built from:
+- **Project name**: extracted from `internalDomain` in `@lib/site.json`
+- **Environment**: from `datocms-environment.ts`
+- **Record info**: `id` + `type` (from `record` prop) → resolved to `itemTypeId` via auto-generated mappings
+
+If any part can't be resolved, the link doesn't render.
+
+### Usage
+
+Pass the `record` prop to `PreviewModeSubscription`:
+
+```astro
+<PreviewModeSubscription
+  query={query}
+  variables={variables}
+  record={{ type: page.__typename, id: page.id }}
+/>
+```
+
+Your GraphQL query needs:
+
+```graphql
+query MyPage {
+  page {
+    id
+    __typename
+    # ... other fields
+  }
+}
+```
+
+### Auto-generated files
+
+- `src/lib/datocms/itemTypes.json` — `__typename` → item type id (generated, in `.gitignore`)
+
+When DatoCMS models change, regenerate:
+
+```bash
+npm run prep:download-item-types
+```

package.json

@@ -32,6 +32,7 @@
     "prep:download-redirects": "jiti scripts/download-redirects.ts",
     "prep:download-site-data": "jiti scripts/download-site-data.ts",
     "prep:download-translations": "jiti scripts/download-translations.ts",
+    "prep:download-item-types": "jiti scripts/download-item-types.ts",
     "prep:icons": "svg-sprite --svg-doctype=false --symbol --symbol-dest='src/assets' --symbol-sprite=icon-sprite.svg src/assets/icons/*.svg && jiti scripts/icon-types.ts",
     "preview": "wrangler pages dev ./dist",
     "lint": "run-s lint:* --print-label",

scripts/download-item-types.ts

@@ -0,0 +1,69 @@
+import { buildClient } from '@datocms/cma-client-node';
+import dotenv from 'dotenv-safe';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { datocmsEnvironment } from '../datocms-environment';
+
+dotenv.config({
+  allowEmptyValues: Boolean(process.env.CI),
+});
+
+function toTypename(apiKey: string): string {
+  const pascalCase = apiKey
+    .split(/[_-]/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('');
+  return `${pascalCase}Record`;
+}
+
+async function downloadItemTypes() {
+  const token = process.env.DATOCMS_API_TOKEN?.trim();
+  const filePath = './src/lib/datocms/itemTypes.json';
+  
+  if (!token) {
+    if (process.env.CI) {
+      console.log(
+        'DATOCMS_API_TOKEN is missing; creating empty itemTypes.json for CI.',
+      );
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, JSON.stringify({}, null, 2));
+      return;
+    }
+    throw new Error(
+      'DATOCMS_API_TOKEN is required. Set it and rerun `npm run prep:download-item-types`.',
+    );
+  }
+
+  const client = buildClient({
+    apiToken: token,
+    environment: datocmsEnvironment,
+  });
+
+  const itemTypes = await client.itemTypes.list();
+  const typenameMap: Record<string, string> = {};
+
+  for (const itemType of itemTypes) {
+    const apiKey = itemType.api_key;
+    if (!apiKey || !itemType.id) continue;
+
+    const typename = toTypename(apiKey);
+    typenameMap[typename] = itemType.id;
+  }
+
+  const sortedEntries = Object.entries(typenameMap)
+    .sort(([a], [b]) => a.localeCompare(b));
+
+  const jsonContent = Object.fromEntries(sortedEntries);
+
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(jsonContent, null, 2));
+
+  console.log('Item types downloaded');
+}
+
+downloadItemTypes()
+  .catch((error) => {
+    console.error('Failed to download item types:', error);
+    process.exit(1);
+  });
+

src/components/PreviewMode/PreviewMode.astro

@@ -1,14 +1,27 @@
 ---
+import siteDataUntyped from '@lib/site.json';
+
+type SiteData = {
+  internalDomain?: string;
+};
+
+const siteData = siteDataUntyped as SiteData;
 const { datocmsEnvironment, datocmsToken, isPreview } = Astro.locals;
+const projectName = siteData.internalDomain?.split('.')[0] || null;
 ---
 <preview-mode
   data-datocms-environment={ datocmsEnvironment }
   data-datocms-token={ isPreview && datocmsToken }
+  data-datocms-project={ projectName }
 >
   <preview-mode-bar>  
     Preview mode
     <span role="presentation" data-status="closed" />
-    <a href={ `/api/preview/exit/?location=${Astro.url}` }>exit preview</a>
+    <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 href={ `/api/preview/exit/?location=${Astro.url}` }>exit preview</a>
+    </div>
   </preview-mode-bar>
   <slot />
 </preview-mode>
@@ -29,6 +42,16 @@ a {
   color: white;
 }
 
+a[data-edit-record]:not([href]) {
+  display: none;
+}
+
+.preview-mode-actions {
+  display: flex;
+  gap: 1em;
+  align-items: center;
+}
+
 [data-status]:before {
   display: inline-block;
   margin-left: .5em;

src/components/PreviewMode/PreviewMode.client.ts

@@ -1,3 +1,4 @@
+import itemTypesJson from '@lib/datocms/itemTypes.json';
 import type { ConnectionStatus as DatocmsConnectionStatus } from 'datocms-listen';
 import { subscribeToQuery } from 'datocms-listen';
 import { atom, map } from 'nanostores';
@@ -17,12 +18,15 @@ type QueryVariables = { query: Query; variables?: Variables };
 class PreviewMode extends HTMLElement {
   barElement: PreviewModeBar;
   subscriptionElements: PreviewModeSubscription[];
+  editableRecord: { id: string, type: string } | null;
+  editLinkElement: HTMLAnchorElement;
   $connections = map<Connection>({});
   $connectionError = atom<boolean>(false);
   $connectionStatus = atom<ConnectionStatus>('closed');
   $updateCounts = map<{ [key: string]: number }>({});
   #datocmsToken: string = '';
   #datocmsEnvironment: string = '';
+  #datocmsProject: string = '';
 
   /**
    * Generates a hashed key for the map tracking subscriptions.
@@ -38,13 +42,22 @@ class PreviewMode extends HTMLElement {
     return hash.toString(36);
   }
 
+  static getItemTypeId (typename?: string): string { 
+    const key = typename as keyof typeof itemTypesJson;
+    return itemTypesJson[key] ?? null;
+  }
+  
   constructor() { 
     super();
 
     this.barElement = this.querySelector('preview-mode-bar') as PreviewModeBar;
     this.subscriptionElements = [...this.querySelectorAll('preview-mode-subscription')] as PreviewModeSubscription[];
+    this.editableRecord = JSON.parse(
+      this.subscriptionElements.find((element) => element.dataset.record)?.dataset.record ?? 'null'
+    );
+    this.editLinkElement = this.querySelector('[data-edit-record]') as HTMLAnchorElement;
 
-    const { datocmsEnvironment, datocmsToken } = this.dataset;
+    const { datocmsEnvironment, datocmsToken, datocmsProject } = this.dataset;
     if (!datocmsEnvironment) {
       console.warn('PreviewMode: missing required data-datocms-environment attribute');
       return;
@@ -55,6 +68,7 @@ class PreviewMode extends HTMLElement {
     }
     this.#datocmsEnvironment = datocmsEnvironment;
     this.#datocmsToken = datocmsToken;
+    this.#datocmsProject = datocmsProject || '';
 
     this.$connections.listen((connections) => {
       // set overall connection status to lowest of all connections:
@@ -97,6 +111,21 @@ class PreviewMode extends HTMLElement {
   getSubscriptionConfigs () {
     return this.subscriptionElements.map((element) => element.getConfig() as QueryVariables);
   }
+
+  connectedCallback() {
+    const record = this.editableRecord;
+    const isLinkableRecord = record?.id && record?.type && this.#datocmsProject;
+    if (!isLinkableRecord || !record) {
+      return;
+    }
+
+    const itemTypeId = PreviewMode.getItemTypeId(record.type);
+    if (!itemTypeId) {
+      return;
+    }
+
+    this.editLinkElement.href = `https://${this.#datocmsProject}.admin.datocms.com/environments/${this.#datocmsEnvironment}/editor/item_types/${itemTypeId}/items/${record.id}`;
+  }
 
   getInstanceCounts () {
     return this.getSubscriptionConfigs()

src/components/PreviewMode/PreviewModeSubscription.astro

@@ -5,19 +5,28 @@ import { print } from 'graphql/language/printer';
 interface Props {
   query: DocumentNode;
   variables?: { [key: string]: string };
+  record?: { type: string; id: string };
 }
-const { query, variables } = Astro.props;
+const { query, variables, record } = Astro.props;
 const { isPreview } = Astro.locals;
 ---
-{ isPreview && (
-  <preview-mode-subscription>
-    <script
-      is:inline
-      type="application/graphql+json" 
-      set:html={ JSON.stringify({
-        query: print(query), 
-        variables 
-      }, null, 2) } 
-    />
-  </preview-mode-subscription>
-)}
+
+{
+  isPreview && (
+    <preview-mode-subscription data-record={JSON.stringify(record)}>
+      <script
+        is:inline
+        type="application/graphql+json"
+        set:html={JSON.stringify(
+          {
+            query: print(query),
+            variables,
+            record,
+          },
+          null,
+          2,
+        )}
+      />
+    </preview-mode-subscription>
+  )
+}

src/content/Pages/index.ts

@@ -1,25 +1,26 @@
-import { defineCollection, z } from 'astro:content';
+import { combine } from '@lib/content';
+import { datocmsCollection, datocmsRequest } from '@lib/datocms';
 import {
+  PageRoute as fragment,
   PageCollectionEntry as query,
   type PageCollectionEntryQuery,
-  PageRoute as fragment,
   type PageRouteFragment,
   type SiteLocale
 } from '@lib/datocms/types';
-import { datocmsCollection, datocmsRequest } from '@lib/datocms';
-import { combine } from '@lib/content';
-import { getPagePath, getParentPages } from '@lib/routing/page';
+import { isLocale } from '@lib/i18n';
 import {
   formatBreadcrumb,
   getPageHref,
   getSlugFromPath,
   type Breadcrumb,
   type PageUrl,
 } from '@lib/routing';
-import { isLocale } from '@lib/i18n';
+import { getPagePath, getParentPages } from '@lib/routing/page';
+import { defineCollection, z } from 'astro:content';
 
-type Meta = {
+type Meta<T extends PageCollectionEntryQuery['record']> = {
   recordId: string; // The record ID of the entry in DatoCMS
+  recordType: NonNullable<T>['__typename']; // The type of the record in DatoCMS
   path: string; // The path of the page, excluding the locale
   locale: SiteLocale;
   breadcrumbs: Breadcrumb[]; // Breadcrumbs for the page, used for navigation
@@ -31,7 +32,7 @@ type QueryVariables = {
 };
 export type PageCollectionEntry = PageCollectionEntryQuery['record'] & {
   id: string, // A unique ID for the entry in the content collection, combining the path and locale
-  meta: Meta,
+  meta: Meta<PageCollectionEntryQuery['record']>,
   subscription: {
     variables: QueryVariables // Variables for the subscription
   }
@@ -78,6 +79,7 @@ const loadEntry = async (path: string, locale?: SiteLocale | null) => {
     id: combine({ id: path, locale }), // Combine the path and locale to create a unique ID for the entry
     meta: {
       recordId: record.id,
+      recordType: record.__typename,
       path,
       locale,
       breadcrumbs,