Vercel Content Link > How to use Vercel Content Link

Vercel Content Link (previously known as Vercel Visual Editing) is an exciting feature offered by Vercel's Edit Mode. It enhances your website by adding clickable links to any content present on the page that's coming from your DatoCMS project. By simply clicking on these links, you'll be seamlessly directed to the corresponding record in DatoCMS.

Once configured for your project, the implementation will resemble the following example:

How does it work?

When Vercel Content Link is enabled, DatoCMS's Content Delivery API incorporates hidden metadata into the response of the GraphQL queries you make.

This is achieved through a smart technique known as steganography. Steganography is the practice of concealing information within other data, and in this case, it involves encoding the metadata into invisible Unicode characters added to the existing strings — you can examine the complete encoding/decoding algorithm in the @vercel/stega NPM pagkage.

Once the "augmented strings" from DatoCMS are used on your pages, Vercel can locate and identify the hidden metadata in the final HTML, and display clickable links that direct you to the corresponding record in DatoCMS.

Which GraphQL fields support Content Link?

Currently, the metadata required to show a clickable link on Vercel is added in the following parts of the GraphQL response:

• Text fields (both Single-line Strings and Multi-paragraph Text) that are not empty and with no format validation: the metadata will be appended at the end of the original string;

• Structured Text fields: the metadata will be appended at the end of the last span node contained in the first paragraph, heading, list, code or blockquote node found in the document;

• The alt field of any Upload referenced in the response: the metadata will be appended at the end of the original string;

We've been conservative in deciding in which cases to embed hidden metadata, so your website should not break when enabling Content Link, but still, it's crucial that you test it thoroughly. If you encounter any problem, please refer to the Troubleshooting section of this guide.

Enabling Content Link

To leverage the powerful capabilities of Content Link, you can follow these straightforward steps to ensure its seamless integration into your workflow.

Step 1: Request activation of Content Link

If you're an Enterprise customer of DatoCMS and a paid customer of Vercel, please contact us at support@datocms.com. By providing the ID of the project where you want to enable Content Link, we'll be able to switch on the feature.

Step 2: Add the Content Link headers to your GraphQL API calls

To communicate to DatoCMS's Content Delivery API that you want Content Link metadata included in your responses, you must add two headers to your API requests:

• X-Visual-Editing is the header that enables the feature, and it must be set to vercel-v1;

• X-Base-Editing-Url is required to generate the right link to your DatoCMS project: it's the base URL of the project on the CMS, and unless you're using a custom domain, it looks like https://example-project.admin.datocms.com

Here is an example of how to add the headers when using the standard fetch API. In this case, we're going to enable Content Link on every preview deployment of the website:

const visualEditingHeaders = process.env.VERCEL_ENV === "preview" ? {
  "X-Visual-Editing": "vercel-v1",
  "X-Base-Editing-Url": "https://<YOUR-PROJECT-NAME>.admin.datocms.com"
} : {}
const response = await fetch(
  "https://graphql-staging.datocms.com/", 
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer <API-KEY>",
      ...visualEditingHeaders,
  },
  body: JSON.stringify({
    query, variables
  }),
});

How you declare the headers depends on the client you're using: please refer to your GraphQL/HTTP client documentation for more info.

Troubleshooting

Although, in general, your website should not break when you enable Content Link, there may be special situations that can cause problems.

Editable elements have the wrong style

In some cases (e.g. when using letter-spacing in CSS), the editable elements could have unexpected styles. In those cases, you can use the functions available in the @vercel/stega library to extract the content and remove steganography data.

Install the library

npm i @vercel/stega

Then you can use a library helper like this:

import { vercelStegaSplit } from '@vercel/stega';
const { cleaned, encoded } = vercelStegaSplit(text);

Links appear for the wrong element

If the wrong element is highlighted when you enable Content Link, you can add the data-vercel-edit-target attribute to one of the parent elements:

<div class="card" data-vercel-edit-target>
  <h1>{editableTitle}</h1>
  <div>Some more text</div>
</div>

That way, even if the editable element is the <h1>, you will have the full card highlighted.

Inspecting Content Link data

Since the metadata added in the GraphQL response is encoded into invisible Unicode characters, it can be quite tricky to examine it.

Fortunately, when you enable Content Link via the Vercel toolbar, a data-vercel-edit-info attribute is added to every element that contains steganography data: