CloudCannon & Astro

Esta página aún no está disponible en tu idioma.

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 Dashbaord 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. You can set collection-level configuration features such as a folder path and output URL, as well as specify which editing views are available to editors working on files in this collection. This can be done through your Site Dashboard or by editing your CloudCannon configuration file directly in your Astro project.

By default, CloudCannon will automatically try to detect appropriate collections (e.g. blog posts, individual pages) when you first create your CloudCannon configuration file by searching your repository files for folders of similar content. You can also manually group files into CloudCannon collections to customize your view.

You can define blank entry templates for your content types by adding one or more CloudCannon schemas. These allow you to quickly create new content entries (e.g. blog posts, newsletters, author pages) through your Site Dashboard that will have the proper default fields, ready to be filled in.

Mapping Astro collections to CloudCannon collections

You will probably choose to make a CloudCannon collection for each Astro content collection, but you may also have additional CloudCannon collections for other types of content. These are used to organize similar file types in your Site Dashboard, but do not necessarily require or enforce metadata themselves like Astro content collections do. For example, you may have a CloudCannon “Pages” collection for standalone pages on your Astro website like About and Contact that share a common URL path for publishing (e.g. example.com/about/ and example.com/contact/), but do not belong to an Astro content collection.

Similarly, a CloudCannon schema is defined separately from your Astro content collection schema. CloudCannon schemas define which fields are available in your CloudCannon editors, but they are not aware of your Astro collection config. It is up to you to make sure that your entries satisfy your content collection.

A good way to ensure that you can use CloudCannon seamlessly with Astro content collections is to create a CloudCannon schema for each Astro content collection. This schema is a template for a new entry, and you can include all the required frontmatter fields to satisfy your Astro content collection’s Zod schema.

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 Cloudflare 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

Configuring multiple schemas

You can have multiple schemas in a single CloudCannon collection (unlike Astro content collections), and schemas may be used in multiple collections. This is because CloudCannon collections are for organizing your files and folders, and themselves do not necessarily enforce any particular data shape.

In the example below, the CloudCanon “Posts” collection has additional schemas for upcoming events and important announcements defined. These may be separate Astro collections, or they may be variations of the post.md template, but with some information filled in.

For example, if you use stock wording for upcoming events you can create an additional CloudCannon schema that satisfies your Astro blog collection with additional content prefilled:

---
title:
author: Events Coordinator
date:
---
New event!

Time:
Date:
Location:

You can then add this to your CloudCannon config file under the same “Posts” collection so that when creating a new content file in your Site Dashboard, you can choose between a regular blog post or an event.

You can even add an announcement schema to multiple CloudCannon collections, though you are responsible for ensuring that each schema file will match a corresponding Astro content collection’s schema property:

collections_config:
posts:
  path: content/blog
  name: Posts
  icon: post_add
  schemas:
    default:
      path: .cloudcannon/schemas/post.md
      name: Blog Post Entry
    events:
      path: .cloudcannon/schemas/events.md
      name: Upcoming Event
    announcements:
      path: .cloudcannon/schemas/announcement.md
      name: Important Announcement
staff:
  path: content/blog
  name: Staff
  icon: people
  schemas:
    default:
      path: .cloudcannon/schemas/announcement.md
      name: New Staff Announcement

Creating a new entry

In your CloudCannon Site Dashboard, you can create new content using the “Add” button. You will be able to select a 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 Dashbaord, 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 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. You will now find a new .md file inside the specified directory for this new post, for example:
- Directorysrc/
  - Directorycontent/
    Directoryblog/
    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>