Visual editing /Visual Editor /Concepts /

How Visual Editor works

Walk through the core concepts of how Visual Editor works by following a developer's typical journey.

Understanding how Visual Editor works is easiest when we follow a developer's typical journey, where each step builds on concepts and practices from those before it.

Try it yourself

You can put many of the concepts in this guide into action by following the getting started tutorial.

# Working modes

You can use the visual editor in local development mode or in cloud setup mode.

# Start with local development

Developers typically start by working locally to build out a visual editing experience to suit their project's needs, while collaborating with content editors occurs in the cloud, which is covered near the end of this guide.

Learn more about Local Development

# Visual Editor development server

Working locally with Visual Editor is made possible by using the CLI. The stackbit dev command runs in parallel with your site's development server to create a visual editing environment that enables developers to prepare a site before bringing in content editors.

See the CLI reference

# Project requirements

Visual Editor is fully composable, which means that most content sources and site frameworks can be supported (with varying levels of required configuration).

Although Visual Editor services a large variety of sites, the one thing all sites have in common — what we consider to be the sole prerequisite — is that content must be structured and separated from code. We think of this as having a content-driven architecture.

# Structured content

For Visual Editor to be able to empower editors to change content, that content must be structured, which means it has a predictable shape, as defined by a content schema.

Visual Editor will inherit content schema when it is defined in the source. When Visual Editor can't infer the schema (e.g. file-based content), you must provide a schema definition through Visual Editor configuration.

Structured content requirements

# Visual Editor configuration

Visual Editor’s behavior for any given project is controlled by the configuration file, stackbit.config.js|ts. Configuration is how Visual Editor knows how to retrieve and store content, which content models represent pages, how editing features should work, and so on.

See the config reference

# Content source connections

Perhaps the most critical configuration property is identifying the source(s) of a site's content, which is (usually) done through the contentSources config property.

Each content source implements Visual Editor’s Content Source Interface, the mechanism that enables two-way content sync between Netlify and the source.

Learn about Content Source Interface

# Content editing

Once a site is properly configured, its content can be immediately edited through Visual Editor.

# Two-way content sync

One of the most powerful capabilities of Visual Editor is its two-way content synching mechanism, which provides the ability to:

Make changes from Visual Editor that get saved back to the content source.
Update content in Visual Editor when changes are made directly at the source.
Automatically update the site preview when content changes have been made.

Dive deep into Two-Way Content Sync

# Traditional CMS editing

When a content source is properly configured, all the models within the source will be available to edit within Visual Editor’s content editor panel.

When working with content from a headless CMS, this requires no additional configuration, as Visual Editor can automatically detect content models and fields from the CMS.

Learn more about the content editor panel

# Basic page editing

To be able to edit with the page editor panel, you must tell Visual Editor which models represent pages. This is handled by content source modules.

See contentSources property reference

Page Editor Panel

# Advanced editing

Editing can then be taken to the next level by enabling editing to click on elements in the preview and make the changes inline. This is made possible by annotating components by adding specific data attributes to inform Visual Editor how the structure of your content maps the elements in the DOM.

# Reusable content

As powerful as inline editing is, it's made even more powerful when content editors can reuse content. Although there are multiple ways to do this, Visual Editor’s content presets feature tends to boost editors' productivity the most.

Learn more about Content Presets

Component Presets View

# Collaboration

When you’re ready to collaborate with content editors in the containerized version of your visual editor in the cloud, you can set up your site for visual editing.

You can do this in these ways:

# Service provisioning

The visual editor provisions services based on your site and configuration. While many of your services will already be configured, the visual editor does the following:

Production Site: the visual editor deploys your site to a [site].stackbit.app site on Netlify, unless your organization is configured to skip this step.
Container: the visual editor creates a container that powers the editing experience for your site. This replaces stackbit dev, used when working locally.

Provisioning configuration options

# Content publishing

Once editors have been added to Visual Editor project, they can begin publishing content to production. This process can also be customized, though it is through the visual editor settings.

# Next steps

This concludes the overview on how Visual Editor works. Here are a few suggestions on what to do next.

# Get started tutorial

Follow the get started tutorial if you haven't. This provides a quick way to put some of these concepts into action.

Follow get started tutorial

# Explore documentation

We've covered a lot of the basics, but there are other features and concepts to explore.

Explore feature guides

Last updated: June 18, 2024

Did you find this doc useful?

Your feedback helps us improve our docs.