💡 Web projects can be hard. Our solutions specialists can help!

How CloudCannon’s live editing works with Astro and Bookshop

By David Large · 5 Jun 2023
How CloudCannon’s live editing works with Astro and Bookshop

CloudCannon supports live visual editing on a wide range of static site generators, bringing intuitive composition, editing, and publishing workflows to everyone. But how do we do it? The short answer: Bookshop, our component development workflow for static websites, which we’ve just expanded to support live visual editing and page-building with Astro.

To help you integrate your existing Astro sites with Bookshop, we’ve created a new Bookshop Astro Guide as part of our documentation. Our Astro Sendit template is also a very helpful reference, as it contains an example site that’s fully integrated with Bookshop’s live visual editing.

While many Astro developers will be accustomed to creating, updating, and removing pages, components, and posts in their IDE, you (and other site users) can also complete all of these tasks within the CMS’s intuitive interface, as pictured above. With the Sendit template, we’ve also allowed users to easily edit our data files with CloudCannon’s Data Editor — meaning information like company details, navigation, footers, and theme colours, stored in .json files in data/, can be accessible and editable for all site users. 

Sendit template screenshot in CloudCannon interface

Getting started with Astro and CloudCannon

Let’s first spin up a new Sendit site on CloudCannon, explore its features, and then poke around the files together. (If you’d rather, you can do this directly via GitHub.)

If you don’t already have a CloudCannon account, take a moment to create one, link your GitHub, GitLab, or Bitbucket account, and create a new Astro Sendit site from a template. Your site files will stay in your Git repo, and upon triggering any save in CloudCannon, your site will build.

Looking at our astro.config.mjs file, there’s not much to it, as you’ll see:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import bookshop from '@bookshop/astro-bookshop';

// https://astro.build/config
export default defineConfig({
site: 'https://top-quail.cloudvent.net/',
integrations: [bookshop(), react()]
});

We’re importing our configuration, as well as Bookshop and React, and declaring our site’s domain. This site: field is temporarily set for you, as above, but you can change this URL to the final, deployed URL of your site.

(Note that all sites built on CloudCannon receive a free preview domain with the format adjective-noun.cloudvent.net — if you don’t already have a final URL for your new Astro site you can set this to your free cloudvent.net domain.)

Separating content and layout

The next thing you might notice about the files in this site is that we’ve separated our page and post content from the layout and routing information — our files in src/content/pages and src/content/blog are in Markdown format, and we’re using […slug].astro files in src/pages for routing. We also use .astro files like Layout.astro, PageLayout.astro, and PostLayout.astro in src/layouts for our layout information and SEO props, but having our content in .md files means CloudCannon can access it in our Content Editor (for WYSIWYG editing) and Visual Editor (for page building and live visual editing).

This way we can get the best of both worlds — Astro’s speed and flexibility for developers, and CloudCannon’s intuitive editing for writers, marketers, and content teams. Building our Astro site is one thing. Astro’s got that under control! But a good site — even one that builds astronomically quickly, with stellar opportunity for future additions — is only as strong as its ease of editing. Editing the pages and posts on our site — and allowing non-technical content writers and marketing teams to do so, as well as to create new content — is something else entirely.

And that’s where CloudCannon’s visual editing comes in.

How Visual Editing works on CloudCannon

As I mentioned above, Sendit is preconfigured for live visual editing on all of its pages, so let’s dig into the feature and see how we’ve set it up for Sendit. In the above video, we saw visual editing in the Sendit homepage’s hero component. The component’s information is stored in two places. Its layout and styling is stored in /src/components/home/hero/hero.jsx:

import MarkdownIt from "markdown-it";
const md = new MarkdownIt({ html: true });

export default function HomeHero(block) {
return (
<section className="hero-two">
<div className="hero-two-shape"></div>
<div className="container-fluid">
<div className="row align-items-center">
<div className="col-lg-6">
<div className="hero-two-content">
<h1 className="mb-4">{block.title}</h1>
<div
className="mb-7 w-xxl-80"
...
/>

<div className="">
{block.button && (
<a
href={block.button.link}
className="btn btn-primary btn-lg"
>

{" "}
{block.button.text}{" "}
</a>
)}
</div>
</div>
</div>
<div className="col-lg-6">
<div className="hero-two-banner">
<img src={block.image} alt={block.image_alt} />
<div className="hero-two-banner-shape"></div>
</div>
</div>
</div>
</div>
</section>
);
}

During the build process (specifically, in our postbuild file), we use our open-source component development tool Bookshop to read the data and default values of our components from .yml files and turn them into inputs config for the editor. For example, here’s src/components/home/hero/hero.bookshop.yml, showing the data and default values (pre-filled text) for this hero component:

# Metadata about this component, to be used in the CMS
spec:
structures:
- content_blocks
label: Home Hero
description: Home Hero section
icon: "cottage"
tags: ["hero"]

# Defines the structure of this component, as well as the default values
blueprint:
title: Email Marketing is the Future for Growing Your Business Revenues
description: We believe that a good email marketing strategy is the key to growth. So we’re helping you grow your business with tools and resources that make email marketing easy.
image: /images/hero/hero-image-2.png
image_alt: Dashboard with reports
button:
text: Try This Free
link: /signup

# Overrides any fields in the blueprint when viewing this component in the component browser
preview:

# Any extra CloudCannon inputs configuration to apply to the blueprint
_inputs:
description:
type: markdown

You’ll see that each component has a defined blueprint, label, icon, and tags, and can include default values. The last few lines of this file add extra definitions to CloudCannon’s inputs configuration; in this case we’re setting our description block as a Markdown text area, unlike title or image_alt, which are plain single-line text inputs by default.

Connecting the dots

Looking at src/layouts/PageLayout.astro below, we can see a component using the bookshop:live directive with props sourced from a frontmatter variable:

---
import Page from "@shared/page";
import Layout, { SEOProps } from "./Layout.astro";

type Props = {
frontmatter: {
title: string;
content_blocks: Array<Record<string, any>>;
seo?: SEOProps;
};
};

if (!Astro.props.frontmatter) {
throw new Error("Page frontmatter must be defined");
}
const props = Astro.props.frontmatter;
---

<Layout {...props}>
<Page bookshop:live contentBlocks={props.content_blocks} />
</Layout>

And in the front matter of our homepage, we can see that content_blocks contains the Bookshop component home/hero.

---
_schema: default
title: Home
seo:
page_description:
canonical_url:
featured_image:
featured_image_alt:
author_twitter_handle:
open_graph_type:
no_index: false
content_blocks:
- _bookshop_name: home/hero
title: Beautiful email campaigns
description: >-
With Sendit, you can quickly create beautiful rich emails that capture a
reader's attention, engage them, and convert them into customers.
image: /images/hero/hero-image-2.png
image_alt: Reports dashboard
button:
text: Try This Free
link: /signup/
...

---

When we view that page in CloudCannon’s Visual Editor, we’ll be able to interact with the component directly on the page. Clicking on the component will open up an editing panel, and our changes will render live on screen.

Global configuration with CloudCannon and Astro

Bringing it all together is CloudCannon’s global configuration file, /cloudcannon.config.yml. Under collections_config at line 5 you’ll see that we can define (or change) a lot of information about our data, posts, and pages, including where content is stored, which schemas are used for posts and pages, and which editor should be enabled to edit them.

# -- truncated -- #
collections_config:
data:
path: data
disable_add: true
disable_add_folder: true
posts:
path: src/content/blog
output: true
url: "/blog/[slug]/"
_enabled_editors:
- content
- visual
add_options:
- name: Add New Post
schema: default
icon: post_add
schemas:
default:
name: New Post
path: schemas/post.md
_inputs:
title:
empty_type: string
image:
empty_type: string
image_alt:
empty_type: string
author:
empty_type: string
tags:
type: multiselect
allow_create: true
empty_type: array
pages:
path: src/content/pages
url: "/[slug]/"
output: true
icon: wysiwyg
_enabled_editors:
- visual
add_options:
- name: Add New Page
schema: default
icon: note_add
schemas:
default:
name: New Page
path: schemas/page.md
new_preview_url: "/"
paginated_collection:
path: schemas/paginated-collection.md
_inputs:
content_blocks:
empty_type: array
filter:
base: strict
# -- truncated -- #

You’ll also see that we’ve enabled the Visual Editor for pages on Sendit, but for posts we also give editors the option to use the Content Editor, which is a configurable WYSIWYG Markdown editor for distraction-free writing. (Users with higher-permission roles such as Developers and Site Owners will also be able to view files in the Source Editor.)

(If your interest is piqued by _inputs, we go into a lot more information about the _inputs configuration in our documentation, which includes a list of all available input types. We also go deep on _editables, which allow you to choose which toolbar controls are available to users in the Content Editor.)

When you’re setting up your own Astro sites on CloudCannon, you can choose which editing (and publishing) features would work best for your site users. With visual editing, branching for staging and production workflows, and top-tier support, CloudCannon’s got you covered.

Where to now?

That brings us to the end of this short and sweet post — we’ve demystified some of the configuration behind our new Astro template within CloudCannon, and we’ve started to define just how CloudCannon lets you and your users interact with your site and its pages. There’s a tremendous amount of power, potential, and flexibility in Bookshop and that cloudcannon.config.yml file, and we’ve barely scratched the surface.

If you'd like to dig into more of the deep configuration options in CloudCannon, check out our documentation on using the configuration cascade, which is a set of sources containing customizable options for the editor, each with a different scope and priority. This allows you to set global defaults and where necessary, override those for specific collections or files.

If you come across any issues while you're dialling in your configuration for Astro, please reach out to us via our support team — we're here to help.

Launch your Astro website today

Give your content team full autonomy on your developer-approved tech stack with CloudCannon.

Get started free!

You might also like: