Netlify Docs
Ask Netlify

Contact

Visual editing /Visual Editor /

Get started with Netlify Visual Editor

Learn how to enable visual editing for your Netlify site.

Netlify Visual Editor is an environment for content editors to work with structured content in a visual way. It is designed for composable architectures, and is compatible with any site framework and API-enabled content source.

If you want to learn more about how Visual Editor works, visit the overview page. Otherwise, let’s enable visual editing for your site.

# Requirements

For the most success getting visual editing working for your site, you should have the following:

  • Site framework that runs a development server on a local port using Node.js v16 or later.
  • Content stored in a supported headless CMS or in individual content files separated from code.

If your site doesn't meet these requirements, you can likely still get visual editing working with additional code and configuration. Contact us for help.

# Content source requirements

If using an API-based CMS, you must also have a user account with read and write access to that content source.

If using file-based content, the content must be defined by a schema that the visual editor can understand. This requires adding content modeling properties to your visual editor configuration file. We’ll cover a bit on configuration later in this guide.

Learn more about how Visual Editor works with structure content.

# Enable visual editing

Visual editing can be enabled under the proper conditions when creating a new Netlify site. Otherwise, it can be enabled for an existing sites.

# Create new site with visual editing

There are a few ways to create a new site with visual editing:

# Use a site template in the UI

To get started with visual editing more quickly, use site templates with the guided setup flow in the UI.

  1. As a Developer or Owner, go to the Sites list page for your team, open the Add new site menu in the upper right, and select Start from a template. The "Sites page" with a list of sites in your team and the "Add site" menu with the "Start from a template" option

  2. Choose a site template with visual editing. You can choose a template that is set up to work with a headless CMS, such as Contentful or Sanity. Or you can choose a template that is set up to work without a headless CMS and that relies on Git to manage content versions for you (also called Git CMS).

    Headless CMS templates:

    Git CMS templates:

    • TypeScript + MUI Starter: good for a tutorial-like experience and learning about visual editor capabilities, doesn’t require content source setup
    • ContentOps Starter: contains over 35 content types, good to try more complex scenarios, doesn’t require content source setup
    • Auto-annotated portfolio: contains auto annotated components, good to learn about auto annotating your own site, doesn’t require content source setup

  3. Clone the template to your Git provider, such as GitHub.

  4. Choose a site and repository name and whether you want the cloned repository to be private or public.

  5. If you chose a headless CMS template, you must sign in to your headless CMS.

  6. Deploy your template site. Netlify applies some default settings but you can update them as needed later.

  7. To complete your visual editor setup, after your first site deploy is successful, go to

    Site configuration Visual Editor
    and select Enable visual editing.

  8. Next, follow the prompts to finish setting up the visual editor for your site and confirm with Save.

To try out visual editing, open the Visual editor in the navigation or under your site overview details.

# Use your own site repository

When creating a site by importing a Git repository, if the repository has a stackbit.config.ts file, visual editor options will appear in the guided setup for your site in the UI.

Visual editing options for creating a new site

To learn more about this flow, check out these import site from existing repository docs.

As you set up your site, you can also confirm your working branch or customize other visual editor settings for your site.

# Start locally with a site template and the CLI

To create a new site repository with a visual editing site template locally, we recommend using the Netlify CLI’s netlify sites:create-template TEMPLATE_REPO_NAME command.

For example, to create the ContentOps site locally, run netlify sites:create-template content-ops-starter.

You can use any of these site templates that already have some visual editor configuration:

After setting up your site locally, you can further customize your site configuration and enable visual editor collaboration in the Netlify UI. Learn more about local development.

# Add content source environment variables

If your site uses an API-based content source, you’ll need to add the appropriate environment variables used in the visual editing configuration file.

Here's an example of adding environment variables for a Contentful content source:

Example environment variables for a site using Contentful

# Add visual editing to an existing site

To add visual editing to an existing site (not a pre-configured template site), follow the UI-guided setup walkthrough.

Before beginning, check that you have successfully:

# 1. Set up the preview environment

To set up the preview environment for the visual editor:

  1. Go to your visual editor site settings at

    Site configuration Visual Editor
    . You’ll find a setup walkthrough in the UI for your site. Select Set up preview environment.

    visual editor settings showing guided UI setup

  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.

  3. Next, select a content source if needed. You’ll be prompted to add environment variables for any new content sources that require this.

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

# 2. Unlock visual editing

To finish the required setup to try out the visual editor, follow the prompts under Unlock visual editing on your visual editor settings page at

Site configuration Visual Editor Unlock visual editing
. If you don’t find this UI, then you may have not completed step 1 to set up your preview environment.

  1. To customize the setup instructions for your site, choose whether your site uses a headless CMS or Git CMS. Note that "Git CMS" describes sites where content is managed in files using Git version control.

    Prompt with option to choose headless CMS or Git CMS

  2. Next follow the in-app guidance on the next steps to take.

Once you’ve successfully completed this step, you can try out the visual editor.

# 3. (Optional) Configure additional settings

After setting up the preview environment and unlocking visual editing, these are the next steps developers typically take to customize the editing experience to match their workflows:

Learn other ways that users customize the visual editing experience.

# Visual Editor access and status

When visual editing is enabled for a site, you can access the visual editor through the following:

  1. the navigation after you select a site in the Netlify UI
  2. in the site details card

Points of access to a site's visual editor UI

# Customize the editing experience

# Unlocking advanced features

After enabling visual editing, these are the next steps developers typically take to customize the editing experience:

# Working locally

It is typically easiest to customize the visual editing experience by running the site locally. This allows you to see changes in real-time and test the editing experience. Learn more about local development for visual editing.

# Disable visual editing

To disable visual editing for a site with visual editing enabled, visit the site settings and choose the Visual editor tab. Select the Disable the visual editor button and confirm you want to stop visual editing for the site.

Disable visual editing for a site button