CloudCannon & Astro

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

CloudCannon is a Git-based headless content management system that provides a visual editor for your content and UI components, providing a rich, live editing experience.

Integrating with Astro

This guide will describe the process of configuring CloudCannon as a CMS for Astro using the CloudCannon Site Dashboard.

The Site Dashboard provides you with an organized view of your Astro files and the ability to edit them using:

A Data Editor for managing structured data files and markup.
A Content Editor for WYSIWYG rich text editing in a minimal view.
A Visual Editor for an interactive preview of your site, allowing you to edit directly on the page.

You can also configure role-based access to a minimal Source Editor, an in-browser code editor for making minor changes to the source code of your files.

Prerequisites

A CloudCannon account. If you don’t have an account, you can sign up with CloudCannon.
An existing Astro project stored locally, or on one of CloudCannon’s supported Git providers: GitHub, GitLab, or Bitbucket. If you do not have an existing project, you can start with CloudCannon’s Astro Starter Template.

Configure a new CloudCannon Site

The following steps will configure a new CloudCannon Site from your dashboard. This Site will connect to an existing Astro repository and allow you to manage and edit your content with CloudCannon’s WYSIWYG text editor.

In your CloudCannon Organization Home page, create a new Site.
Authenticate your Git provider and select the Astro repository you want to connect to.
Choose a name for your Site, then CloudCannon will create the Site and start syncing your files.
Follow CloudCannon’s guided tasks in your Site dashboard for completing your Site setup, including creating a CloudCannon configuration file (cloudcannnon.config.yml)
Save your configuration file to commit it with your CloudCannon preferences to your Git repository.

You can now explore your Site Dashboard to see your Astro files and edit them with the Content Editor.

You may also want to take advantage of some CloudCannon features, such as organizing your files into collections, creating CloudCannon schemas, and setting up your project for visual editing.

For more detailed instructions, see CloudCannon’s Getting Started Guide.

CloudCannon collections and schemas

If you use Astro’s content collections, then you will be familiar with CloudCannon’s concepts of collections (used for organization/navigation in your Site Dashboard) and schemas (used to define the format of new content entries).

Your CloudCannon Site Dashboard allows you to organize your Astro project’s pages and content into collections: groups of related files with a similar format. This allows you to see similar types of content together for ease of editing and makes your content files easy to navigate, sort, and filter.

Create a CloudCannon schema for a collection

To ensure that the data properties of your CloudCannon entries match the Zod validation schema defined in your content collection, you can create a CloudCannon schema (a blank template document for creating a new entry). Creating a template schema can ensure that any new documents created in CloudCannon will have the properties required by your content collection and avoid type errors in your project. Your CloudCannon schema can also include default values to start new documents, such as an author name for a single-person blog.

The following example will create a CloudCannon schema based on an Astro content collection (blog) for blog posts written in Markdown. This schema will be available when creating a new entry from the CloudCannon “Posts” collection:

Create a folder at .cloudcannon/schemas/ if it does not already exist.
Add an existing blank file in this folder to be used as a default blog post template. The name is unimportant, but the file must have the same file extension as your Astro content collection entries (e.g. post.md).
Provide the necessary frontmatter fields required by your content collection’s schema. You do not need to provide any values for these, but any content you do include will be automatically included when a new entry is created. These are fields that will be available in the sidebar of your Content Editor.

The following example schema for a blog post has placeholders for the title, author, and date:
.cloudcannon/schemas/post.md
```
---
title:
author:
date:
---
```

In your CloudCannon configuration file’s collections_config property, add the file path to your schema under the CloudCannon collection under the “Posts” collection.

collections_config:
  posts:
    path: content/blog
    name: Posts
    icon: post_add
    schemas:
      default:
        path: .cloudcannon/schemas/post.md
        name: Blog Post Entry

Creating a new entry

In your CloudCannon Site Dashboard, you can create new content using the “Add” button. You will be able to select an entry type from the schemas you have defined in cloudcannon.config.yml, depending on which collection you are currently in.

You can also upload files to CloudCannon, or create new files directly in your Astro project. When you save your Site changes, new files created in either location will be synchronized and available in both CloudCannon and your Astro project.

The following example will create a new blog post from the CloudCannon Site Dashboard “Posts” collection using the post.md template schema created to satisfy the blog Astro content collection:

In the CloudCannon Site Dashboard, navigate to the collection representing the kind of content you want to add. For example, navigate to the “Posts” collection to add a new blog post.
Use the “Add” button to create a new post. If you have configured CloudCannon’s post.md schema, then you can choose the default blog post entry to create a new post.
Fill the necessary fields in the sidebar of your Content Editor (e.g. title, author, date), and post content and save your post.
This post is saved locally in CloudCannon and should now be visible from your Site Dashboard in your “Posts” collection. You can view and edit all your individual posts from this dashboard page.
When you are ready to commit this new post back to your Astro repository, select “Save” in the Site navigation sidebar from your Site Dashboard. This will show you all unsaved changes made to your site since your last commit back to your repository and allow you to review and select which ones to save or discard.
Return to view your Astro project files and pull new changes from git. You will now find a new .md file inside the specified directory for this new post, for example:
- Ordnersrc/
  - Ordnercontent/
    Ordnerblog/
    my-new-post.md

Navigate to that file in your code editor and verify that you can see the Markdown content you entered. For example:

---
title: My New Post
author: Sarah
date: 2025-11-12
---

This is my very first post created in CloudCannon. I am **super** excited!

Rendering CloudCannon content

Use Astro’s Content Collections API to query and display your posts and collections, just as you would in any Astro project.

Displaying a collection list

The following example displays a list of each post title, with a link to an individual post page.

---
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');
---
<ul>
  {posts.map(post => (
    <li>
      <a href={`/posts/${post.slug}`}>{post.data.title}</a>
    </li>
  ))}
</ul>

Displaying a single entry

To display content from an individual post, you can import and use the <Content /> component to render your content to HTML:

---
import { getEntry, render } from 'astro:content';

const entry = await getEntry('blog', 'my-first-post');
const { Content } = await render(entry);
---

<main>
  <h1>{entry.data.title}</h1>
  <p>By: {entry.data.author}</p>
  <Content />
</main>

For more information on querying, filtering, displaying your collections content, and more, see the full content collections documentation.

Deploying CloudCannon + Astro

To deploy your website, visit our deployment guides and follow the instructions for your preferred hosting provider.

Configure Visual Editing

CloudCannon’s Visual Editor allows you to see and edit text, images, and other content in a live, interactive preview of your site. These updates can be made using editable regions, data panels, and the sidebar.

Follow CloudCannon’s guide to set up visual editing (also available in your Site Dashboard). This will show you how to define editable regions of your live preview by setting HTML data- attributes on DOM elements, or by inserting web components.

For example, the following template creates an editable author value that can be updated in the live preview:

<p>By: <editable-text data-prop="author">{author}</editable-text></p>

Visual Editing with components

CloudCannon allows you to define Component Editable Regions for live re-rendering of Astro components in the Visual Editor. This gives you the same interactive editing experience for your Astro components.

Install the @cloudcannon/editable-regions package.
- npm
- pnpm
- Yarn
Terminal window
npm install @cloudcannon/editable-regions
Terminal window
pnpm add @cloudcannon/editable-regions
Terminal window
yarn add @cloudcannon/editable-regions

Add the editableRegions integration to your Astro config:

import { defineConfig } from 'astro/config';
import editableRegions from "@cloudcannon/editable-regions/astro-integration";

export default defineConfig({
  // ...
  integrations: [editableRegions()],
  // ...
});

Follow CloudCannon’s instructions to register your components. This tells CloudCannon that those components should be bundled for client-side use in the Visual Editor.

Add the appropriate attributes to your components for visual editing. For example, the following CTA.astro component properties, such as description and button color, can be updated in CloudCannon’s Visual Editor:

---
const { description, link, buttonText, buttonColor } = Astro.props;
---

<p data-editable="text" data-prop="description">{description}</p>
<a href={link}>
    <span data-editable="text" data-prop="buttonText" style={`background-color: ${buttonColor}`}>{buttonText}</span>
</a>