add preview links from CMS to website pages (#304)

# Associated issue

Part of #10
Closes #233

## Description

This PR adds **preview links** to the DatoCMS sidebar so editors can
click a link and immediately see the page they're working on: on
localhost, the preview environment, or production. We are installing the
[Model Deployment Links
plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-model-deployment-links)
in DatoCMS which adds preview links to the sidebar. When an editor
clicks one, it opens the page on the website.

This is a rebased and updated version of `feat/preview-links`, #233
updated with the current `main` branch



For **Home** and **Not Found** pages, the URL is simple and known
(`/{locale}/` and `/{locale}/404`). But for **regular pages**, the CMS
only knows the page's slug (e.g. `my-page`), not the full url path,
because pages can be nested (`/en/parent/my-page/`). To solve this, we
added a reroute endpoint that looks up the page by slug and redirects to
the correct url.

## How it works
1. Editor clicks "Preview" in the CMS sidebar
2. Browser opens:
/api/preview/enter/?secret=xxx&location=/api/reroute/page/en/my-page
3. Preview enter endpoint checks the secret, sets a preview cookie,
redirects to location
4. Reroute endpoint looks up the page by slug, finds its full path
5. Redirects to: /en/parent/my-page/
6. Editor sees the page (including draft/unpublished content)

## Changes from the original PR (`feat/preview-links`) #233 

- Rebased onto current `main` (content layer, new routing, etc.)
- Changed reroute endpoint from query params
(`/api/reroute/page?locale=en&slug=foo`) to **path-based**
(`/api/reroute/page/en/foo`) — the query param approach had a bug where
the DatoCMS plugin didn't URL-encode the `location` parameter, causing
the slug to be lost
- Migration now creates the Preview API token automatically (no manual
setup needed)
- Migration checks for existing plugin/token before creating duplicates
- Updated documentation

## How to test

1. Create a new DatoCMS sandbox environment and run migrations (`npm run
cms:manage`)
2. Start the dev server (`npm run dev`)
3. Open the CMS, go to the sandbox environment
4. Open a Page / Home / Not Found record and check the sidebar preview
links:
   - Home > Opens `/{locale}/` directly
- Page > Opens `/api/reroute/page/{locale}/{slug}` : redirects to the
full canonical URL (`/en/parent/child/`)
   - Not found > Opens `/{locale}/404`

5. Verify that:
- Preview links work for all three models (via the Localhost build
trigger)
   - Nested pages (with parent pages) resolve to the correct url


> **Note:** Preview and Production sidebar links will only work once the
code is deployed to those environments.

# Checklist

- [x] I have performed a self-review of my own code
- [x] I have made sure that my PR is easy to review (not too big,
includes comments)
- [x] 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) -->

---------

Co-authored-by: Jasper Moelker <jasper@voorhoede.nl>

Author: anareyna

config/datocms/lib/createPreviewToken.ts

@@ -0,0 +1,26 @@
+import type { Client } from '@datocms/cli/lib/cma-client-node';
+
+export const createPreviewToken = async (client: Client) => {
+  // Check if a token named "Preview" already exists
+  const existingTokens = await client.accessTokens.list();
+  const existingPreviewToken = existingTokens.find((token) => token.name === 'Preview');
+  
+  if (existingPreviewToken) {
+    return existingPreviewToken;
+  }
+
+  // Create new token if it doesn't exist
+  const roles = await client.roles.list();
+  const editorRole = roles.find((role) => role.name === 'Editor');
+
+  return client.accessTokens.create({
+    name: 'Preview',
+    can_access_cda: true,
+    can_access_cda_preview: false,
+    can_access_cma: true,
+    role: {
+      type: 'role',
+      id: editorRole!.id,
+    },
+  });
+};

config/datocms/migrations/1750900000_previewLinks.ts

@@ -0,0 +1,74 @@
+import type { Client } from '@datocms/cli/lib/cma-client-node';
+import { createPreviewToken } from '../lib/createPreviewToken';
+
+export default async function (client: Client) {
+  console.log('Manage upload filters');
+
+  console.log('Install plugin "Model Deployment Links"');
+  const previewApiToken = await createPreviewToken(client);
+  
+  // Check if plugin already exists
+  const existingPlugins = await client.plugins.list();
+  let plugin = existingPlugins.find((p) => p.package_name === 'datocms-plugin-model-deployment-links');
+  
+  if (!plugin) {
+    plugin = await client.plugins.create({
+      package_name: 'datocms-plugin-model-deployment-links',
+    });
+  }
+  
+  await client.plugins.update(plugin.id, {
+    parameters: { datoApiToken: previewApiToken.token },
+  });
+
+  console.log('Creating new fields/fieldsets');
+
+  const page = await client.itemTypes.find('page');
+  const homePage = await client.itemTypes.find('home_page');
+  const notFoundPage = await client.itemTypes.find('not_found_page');
+
+  console.log(
+    'Create JSON field "Preview" (`preview`) in model "\uD83D\uDCD1 Page" (`page`)'
+  );
+  await client.fields.create(page.id, {
+    label: 'Preview',
+    field_type: 'json',
+    api_key: 'preview',
+    localized: true,
+    appearance: {
+      addons: [],
+      editor: plugin.id,
+      parameters: { urlPattern: '/api/reroute/page/{ locale }/{ slug }' },
+    },
+  });
+
+  console.log(
+    'Create JSON field "Preview" (`preview`) in model "\uD83C\uDFE0 Home" (`home_page`)'
+  );
+  await client.fields.create(homePage.id, {
+    label: 'Preview',
+    field_type: 'json',
+    api_key: 'preview',
+    localized: true,
+    appearance: {
+      addons: [],
+      editor: plugin.id,
+      parameters: { urlPattern: '/{ locale }/' },
+    },
+  });
+
+  console.log(
+    'Create JSON field "Preview" (`preview`) in model "\uD83E\uDD37 Not found" (`not_found_page`)'
+  );
+  await client.fields.create(notFoundPage.id, {
+    label: 'Preview',
+    field_type: 'json',
+    api_key: 'preview',
+    localized: true,
+    appearance: {
+      addons: [],
+      editor: plugin.id,
+      parameters: { urlPattern: '/{ locale }/404' },
+    },
+  });
+}

docs/getting-started.md

@@ -73,6 +73,15 @@ You can now run your project locally:
 npm run dev
 ```
 
+### Configure DatoCMS plugins
+
+Head Start comes with a few DatoCMS plugins pre-installed. The [Model Deployment Links plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-model-deployment-links) is configured automatically when running migrations. It adds preview links to the CMS sidebar so editors can preview pages directly from the CMS.
+
+If you need to configure the plugin manually (e.g. when not using migrations):
+
+- In your DatoCMS instance go to Project Settings > API Tokens (`/project_settings/access_tokens`) and "Add a new access token". Name it "Preview" (or whatever you prefer), for the "Role associated with this API token" select "Editor" and keep the other settings as is.
+- Go to Environment Configuration > Plugins > Model Deployment Links and enter the newly created access token in the plugin settings under "DatoCMS API Token".
+
 ### Add DatoCMS secrets to repository
 
 Head Start provides GitHub Actions which include linting code and validating HTML on PR changes. These Actions require the DatoCMS tokens to be available.

docs/preview-mode.md

@@ -38,7 +38,7 @@ Preview mode is protected with a secret. If you attempt to view content protecte
 /api/preview/enter/?secret=my-little-secret&location=/en/some-page/
 ```
 
-This endpoint can for example be used to link to previews from within the CMS.
+This endpoint is used by the CMS preview links (see [Preview links from the CMS](#preview-links-from-the-cms) below).
 
 When authorised an encrypted cookie is set, to persist preview mode throughout a session. Calling the 'exit preview mode' endpoint removes the cookie and disables preview mode:
 
@@ -52,6 +52,26 @@ When authorised an encrypted cookie is set, to persist preview mode throughout a
 
 Note: the secret is configured as environment variable `HEAD_START_PREVIEW_SECRET`.
 
+## Preview links from the CMS
+
+Head Start includes the [Model Deployment Links plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-model-deployment-links) which adds preview links to the CMS sidebar. This allows editors to preview any page directly from the CMS, including draft (unpublished) content.
+
+The plugin is configured automatically via migrations (see [`1750900000_previewLinks.ts`](../config/datocms/migrations/1750900000_previewLinks.ts)). It adds a "Preview" field to the Home, Page, and Not Found models with URL patterns for each.
+
+### How it works
+
+Each model has a different URL pattern:
+
+| Model | URL pattern | How it resolves |
+|---|---|---|
+| Home | `/{ locale }/` | Direct link to the home page |
+| Page | `/api/reroute/page/{ locale }/{ slug }` | Looks up the page by slug, 307 redirects to its canonical URL |
+| Not found | `/{ locale }/404` | Direct link to the 404 page |
+
+The **Page** model uses a reroute endpoint because the CMS only knows a page's slug, not its full nested path (e.g. a page with slug `my-page` might live at `/en/parent/my-page/`). The endpoint at `src/pages/api/reroute/page/[locale]/[slug].ts` queries DatoCMS for the page by slug and redirects to the correct canonical URL.
+
+The sidebar links are shown for each Build Trigger configured in DatoCMS (e.g. Localhost, Preview, Production).
+
 ## Preview mode subscriptions
 
 In preview mode the web page listens for content changes and automatically reloads to re-render on updates. To configure which content changes to listen to you can add one or more `PreviewModeSubscription` components, which accept the same `query` and `variables` properties you use to request the initial data:

src/pages/404.astro

@@ -1,28 +1,26 @@
 ---
-import type { NotFoundPageQuery, SiteLocale } from '@lib/datocms/types';
-import { datocmsRequest } from '@lib/datocms';
-import { noIndexTag, titleTag } from '@lib/seo';
-import Layout from '@layouts/Default.astro';
 import Blocks from '@blocks/Blocks.astro';
 import PreviewModeSubscription from '@components/PreviewMode/PreviewModeSubscription.astro';
+import Layout from '@layouts/Default.astro';
+import { datocmsRequest } from '@lib/datocms';
+import type { NotFoundPageQuery, SiteLocale } from '@lib/datocms/types';
+import { noIndexTag, titleTag } from '@lib/seo';
 import query from './_404.query.graphql';
 
 export const prerender = false;
 
 Astro.response.status = 404;
 
-type Params = {
-  locale: SiteLocale;
-};
-
-const { locale } = Astro.params as Params;
+const localeFromPath = Astro.params.locale as SiteLocale;
+const localeFromQuery = Astro.url.searchParams.get('locale') as SiteLocale;
+const locale = localeFromQuery || localeFromPath;
 const variables = { locale };
 // While this page is not prerendered, we still want to treat it as a regular page with the default prerender strategy.
 const { page } = await datocmsRequest<NotFoundPageQuery, true>({ query, variables });
 ---
 
 <Layout pageUrls={[]} seoMetaTags={[noIndexTag, titleTag(page.title)]}>
   <PreviewModeSubscription query={query} variables={variables} record={{ type: page.__typename, id: page.id }} />
-  <h1>{page.title} {Astro.params.locale}</h1>
+  <h1>{page.title}</h1>
   <Blocks blocks={page.bodyBlocks} />
 </Layout>

src/pages/[locale]/[...path]/index.astro

@@ -14,17 +14,22 @@ export async function getStaticPaths() {
 
 // Load as an entry so this route can also be a server route in preview mode.
 // @see /docs/preview-mode.md
-const { path } = Astro.params;
+const { locale, path } = Astro.params;
 const entry = await getEntry('Pages', path);
 if (!entry) {
-  return Astro.redirect('/404', 404);
+  return Astro.rewrite(`/404/?locale=${locale}`);
 }
 
 const {
   data: { meta, ...page },
   subscription,
 } = entry;
 const { breadcrumbs, pageUrls, recordId, recordType } = meta;
+
+const canonicalUrl = pageUrls.find((url) => url.locale === meta.locale)?.pathname;
+if (canonicalUrl && Astro.url.pathname !== canonicalUrl) {
+  return Astro.redirect(canonicalUrl);
+}
 ---
 
 <Layout
@@ -39,4 +44,4 @@ const { breadcrumbs, pageUrls, recordId, recordType } = meta;
   />
   <h1>{page.title}</h1>
   <Blocks blocks={page.bodyBlocks} />
-</Layout>
+</Layout>

src/pages/api/reroute/_page.query.graphql

@@ -0,0 +1,7 @@
+#import '@lib/routing/PageRoute.fragment.graphql'
+
+query ReroutePage($locale: SiteLocale!, $slug: String!) {
+  page(locale: $locale, filter: { slug: { eq: $slug } }) {
+    ...PageRoute
+  }
+}

src/pages/api/reroute/page/[locale]/[slug].ts

@@ -0,0 +1,38 @@
+import type { APIRoute } from 'astro';
+import { datocmsRequest } from '@lib/datocms';
+import type { ReroutePageQuery, SiteLocale } from '@lib/datocms/types';
+import { getPageHref } from '@lib/routing';
+import query from '../../_page.query.graphql';
+
+export const prerender = false;
+
+const jsonResponse = (data: object, status: number = 200) => {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  });
+};
+
+export const GET: APIRoute = async ({ params }) => {
+  const locale = params.locale as SiteLocale;
+  if (!locale) {
+    return jsonResponse({ error: 'Missing \'locale\' parameter' }, 400);
+  }
+
+  const slug = params.slug;
+  if (!slug) {
+    return jsonResponse({ error: 'Missing \'slug\' parameter' }, 400);
+  }
+
+  const { page } = (await datocmsRequest<ReroutePageQuery>({ query, variables: { slug, locale } }));
+  if (!page) {
+    return jsonResponse({ error: 'Page not found' }, 404);
+  }
+
+  return new Response('', {
+    status: 307,
+    headers: { 'Location': getPageHref({ locale, record: page }) },
+  });
+};