Visual editor walkthrough help

Get extra guided help as you add visual editing to an existing site in the Netlify UI.

Once you have successfully deployed your site and enabled the visual editor, you’ll find guided help configuring the visual editor in the Netlify UI in your visual editor site settings at Project configuration > Visual Editor .

For even more guided help, you can consult this doc as you go along through the Netlify UI’s guided help.

This doc also helps you get started before the walkthrough help is activated.

Different setup path?

There are many ways to set up the visual editor. To find another setup path, check out our docs on choosing the best setup path for you.

Before you begin

Check that you have successfully:

• confirmed your site meets the visual editor requirements
• deployed your site
• enabled visual editing

Step 1: Deploy site to Netlify

Skip to the next step if your site is already successfully deployed on Netlify.

If you haven’t already, deploy your site to Netlify. This allows you to confirm that your site can successfully deploy to Netlify first.

1. From the Netlify dashboard for your team, go to the projects list page at app.netlify/[YOUR-TEAM-NAME]/projects.

2. Select Add new project, then select Import an existing project. Be sure you know your site repository name.

   

3. Follow the guided setup to deploy your site to Netlify. After this setup, Netlify will deploy your site to an internal Netlify domain, such as https://YOUR-SITE-NAME.netlify.app (unless you have an automatic deploy domain configured).

Checkpoint

Your site should have successfully deployed to Netlify. If not, we recommend investigating any build errors you get with Build troubleshooting tips. You can leave feedback about any template site you used and

Step 2: Set up the preview environment

From your visual editor settings page, you’ll find the setup walkthrough in the Netlify UI.

To set up the preview environment for the visual editor:

1. Go to your visual editor site settings at Project configuration > Visual Editor and select Set up preview environment.

2. Choose your working branch. For most cases, we recommend preview for your working branch. You can pick from any of your repository’s branches that are not the primary publishing branch such as main or master. If preview is chosen, a new preview branch will be added to the repository.

   If your content is stored in a headless CMS, ensure environment variables are configured under project configuration > Environment variables. Learn how to set up environment variables, check out supported sources.

3. Authorize access to your site repository:

   • For site repositories hosted on GitHub, install the GitHub app for the Netlify visual editor and follow the necessary prompts.
   • For site repositories hosted on BitBucket, add your access key and install the BitBucket app if prompted

   If you’re having access issues, check out our troubleshooting resources.

4. Exit any remaining access setup windows and select Save.

The visual editor configuration file will be added to your site repository with the content source defined and any environment variables you selected.

Checkpoint

Now Netlify should be authorized to have access to your site repository for your visual editor preview environment.

If this is not true:

• be sure that you have the right access and permissions in your Git provider
• note that only GitHub or BitBucket are supported at this time
• let us know in the docs feedback form at the bottom of this page if you are still stuck and related context.

Step 4: Configure visual editing

Configuring the page editor helps you unlock visual editing so you can try out visual editing and collaborate on Netlify.

Choose whether you are configuring the page editor for a site with Git CMS or headless CMS.

Unlock visual editing for Git CMS

To configure the page editor, you need to tell the visual editor:

• how your content is structured
• how your site’s content matches the visual editor’s content model types for a page
• where to find your content files (only necessary for Git CMS)

Quick overview - Models for visual editor

To configure the page editor for a site using no CMS (or storing content in files):

1. Go to your site’s stackbit.config.ts file and define the structure of your content with the models property by specifying your model type and name.

For example, if you have a content file in Markdown with this frontmatter in a file called content/pages/my-first-post.md:

---
type: Post # The `type` property is a reserved word that tells the visual editor which model this content file belongs to
title: My post title
---

My post body

You’ll add your content structure like this, where filePath describes where to find your content and fields describes your frontmatter properties:

// stackbit.config.ts
import { defineStackbitConfig } from "@stackbit/types";
import { GitContentSource } from "@stackbit/cms-git";

export default defineStackbitConfig({
  // ...
  contentSources: [
    new GitContentSource({
      rootPath: __dirname,
      contentDirs: ["content"],
      models: [
        {
          name: "Post",
          urlPath: "/{slug}",
          // Tell the visual editor where to find content
          filePath: "content/pages/{slug}.md",
          fields: [{ name: "title", type: "string", required: true }]
        }
      ],
    })
  ]
});

For this content file, the visual editor would infer a document looking like:

{
  // There would be more fields but the "fields" key is what I was trying to highlight
  "id": "/content/pages/my-first-post.md",
  "fields": [
    { name: "title", type: "string", required: true, value: "My post title" },
    { name: "slug", type: "slug", value: "my-first-post",
    // not sure if the type here is true
    { name: "markdown_content", value: "My post body", type: "markdown_content" }
  ]
}

2. Next, tell the visual editor which models (structured data objects) represent pages.

   For example, add the type property:

      // stackbit.config.ts
    import { defineStackbitConfig } from "@stackbit/types";
    import { GitContentSource } from "@stackbit/cms-git";

    export default defineStackbitConfig({
      // ...
      contentSources: [
        new GitContentSource({
          rootPath: __dirname,
          contentDirs: ["content"],
          models: [
            {
              name: "Post",
              type: "page",
              urlPath: "/{slug}",
              filePath: "content/pages/{slug}.md",
              fields: [{ name: "title", type: "string", required: true }]
            }
          ],
        })
      ]
    });

3. To let the visual editor know where your content lives, specify the URL path for your pages. This connects page models to specific URLs. There are two ways to do this. You can add a siteMap function which offers more control (most commonly used) or take a static route and specify the urlPath property for each page model in the modelExtensions property.

Example specifying urlPath

In this example, you specify urlPath property for each model defined in your modelExtensions property:

stackbit.config.ts

// stackbit.config.ts
import { defineStackbitConfig, SiteMapEntry } from "@stackbit/types";

export default defineStackbitConfig({
  // ...
  contentSources: [
    new GitContentSource({
      rootPath: __dirname,
      contentDirs: ["content"],
      models: [
        {
          name: "Post",
          type: "page",
          // Static URL path derived from the "slug" field
          urlPath: "/{slug}",
          filePath: "content/pages/{slug}.md",
          fields: [{ name: "title", type: "string", required: true }]
        },
        // ...
      ],
    })
  ],
});

Unlock visual editing for headless CMS

In general, the visual editor automatically inherits the schema (collection of models) from the API CMS.

However, most Headless CMS options don’t have the concept of a “page” in their content model so you need to tell the visual editor what counts as a page with the modelExtensions property.

Quick overview - Models for visual editor

To configure the page editor for a site using headless CMS:

1. Go to your site’s stackbit.config.ts file and tell the visual editor which of your models (or structured data objects) are pages.

For example, if your CMS has a model called post , then you can indicate it’s a page model by implementing the modelExtensions property with { name: "post", type: "page" }:

 // stackbit.config.ts
 import { defineStackbitConfig } from "@stackbit/types";

 export default defineStackbitConfig({
   // ...
   modelExtensions: [
     // Extend the "page" and "post" models by defining them as page models
     { name: "post", type: "page" }
   ]
 });

Now that we know which models are pages, we need to connect them to URL routes so the visual editor knows where your site’s editable pages are.

2. To connect page models to URLs, you can add a siteMap function which offers more control (most commonly used) or take a static route and specify the urlPath property for each page model in the modelExtensions property.

Step 5. Restart the preview

1. Confirm you have merged changes you made in stackbit.config.ts into the visual editor’s working branch, which is preview by default, on your site’s remote repository on GitHub or BitBucket.

2. If the Preview Server for the visual editor was already running, it will automatically restart. If the Preview Server was not already running, it will start automatically when you open visual editor.

You can verify that your Preview Server has restarted by going to Preview Servers.

Step 6. Try the visual editor

After the Preview Server has successfully restarted, you can try the visual editor.

1. From your site overview, select Open visual editor.

Checkpoint

You should now be able to open the visual editor and use the page editor to make changes to your site.

If this is not true, let us know in the docs feedback form at the bottom of this page. More details are helpful.

Next steps

For next steps, you can customize the visual editor further for your team’s workflow and explore its advanced features.

Developers typically further customize visual editing by:

• Enabling inline editing to make changes directly in the preview
• Configuring asset sources

Learn more about how to customize the visual editing experience.