Refresh CloudCannon CMS guide

src/content/docs/en/guides/cms/cloudcannon.mdx

@@ -9,27 +9,329 @@ service: CloudCannon
 i18nReady: true
 ---
 
-import Grid from '~/components/FluidGrid.astro'
-import Card from '~/components/ShowcaseCard.astro'
+import Grid from '~/components/FluidGrid.astro';
+import Card from '~/components/ShowcaseCard.astro';
+import { Steps, FileTree } from '@astrojs/starlight/components';
+import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
 
-[CloudCannon](https://cloudcannon.com) is a Git-based headless content management system that provides a visual editor for your content.
+[CloudCannon](https://cloudcannon.com) 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.
+
+:::tip
+If you're starting a project from scratch, you can use the [CloudCannon Astro Starter Template](https://cloudcannon.com/templates/astro-starter/) with commonly used CloudCannon features to cut down on setup time.
+:::
+
+## 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](https://cloudcannon.com/documentation/articles/the-data-editor/) for managing structured data files and markup.
+- A [Content Editor](https://cloudcannon.com/documentation/articles/the-content-editor/) for WYSIWYG rich text editing in a minimal view.
+- A [Visual Editor](https://cloudcannon.com/documentation/articles/the-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](https://cloudcannon.com/documentation/articles/the-source-editor/), an in-browser code editor for making minor changes to the source code of your files.
+
+## Prerequisites
+
+{/* TODO: Does CloudCannon want a particular UTM link? */}
+
+1. A CloudCannon account. If you don’t have an account, you can [sign up with CloudCannon](https://app.cloudcannon.com/register).
+2. 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](https://cloudcannon.com/templates/astro-starter/).
+
+## 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.
+
+<Steps>
+
+1. In your CloudCannon Organization Home page, create a new Site.
+2. Authenticate your Git provider and select the Astro repository you want to connect to.
+3. Choose a name for your Site, then CloudCannon will create the Site and start syncing your files.
+4. Follow CloudCannon's guided tasks in your Site dashboard for completing your Site setup, including creating a CloudCannon configuration file (`cloudcannnon.config.yml`)
+5. Save your configuration file to commit it with your CloudCannon preferences to your Git repository.
+
+</Steps>
+
+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](#cloudcannon-collections-and-schemas), [creating CloudCannon schemas](#create-a-cloudcannon-schema-for-a-collection), and setting up your project for [visual editing](#configure-visual-editing).
+
+For more detailed instructions, see [CloudCannon's Getting Started Guide](https://cloudcannon.com/documentation/guides/getting-started-with-cloudcannon/).
+
+## CloudCannon collections and schemas
+
+If you use [Astro's content collections](/en/guides/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](https://cloudcannon.com/documentation/guides/getting-started-with-cloudcannon/group-files-into-collections/) to customize your view.
+
+You can define blank entry templates for your content types by adding one or more [CloudCannon schemas](https://cloudcannon.com/documentation/articles/what-is-a-schema/). 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](https://cloudcannon.com/documentation/articles/what-is-a-collection/) 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](#create-a-cloudcannon-schema-for-a-collection) 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](https://cloudcannon.com/documentation/articles/what-is-a-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](#creating-a-new-entry) from the CloudCannon "Posts" collection:
+
+<Steps>
+
+1. Create a folder at `.cloudcannon/schemas/` if it does not already exist.
+2. 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`).
+3. 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:
+
+      ```markdown title=".cloudcannon/schemas/post.md"
+      ---
+      title:
+      author:
+      date:
+      ---
+
+      ```
+4. In your Cloudflare configuration file's `collections_config` property, add the file path to your schema under the CloudCannon collection under the "Posts" collection.
+
+      ```yml title="cloudcannon.config.yml" ins={6-9}
+      collections_config:
+        posts:
+          path: content/blog
+          name: Posts
+          icon: post_add
+          schemas:
+            default:
+              path: .cloudcannon/schemas/post.md
+              name: Blog Post Entry
+      ```
+</Steps>
+
+### 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:
+
+```markdown title=".cloudcannon/schemas/event.md"
+---
+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:
+
+```yml title="cloudcannon.config.yml"
+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:
+
+<Steps>
+1. 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.
+
+2. 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.
+
+3. Fill the necessary fields in the sidebar of your Content Editor (e.g. `title`, `author`, `date`), and post content and save your post.
+
+3. 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.
+
+4. 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.
+
+5. 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:
+    <FileTree title="Project Structure">
+    - src/
+      - content/
+        - blog/
+          - **my-new-post.md**
+    </FileTree>
+
+5. Navigate to that file in your code editor and verify that you can see the Markdown content you entered. For example: 
+      ```markdown
+      ---
+      title: My New Post
+      author: Sarah
+      date: 2025-11-12
+      ---
+
+      This is my very first post created in CloudCannon. I am **super** excited!
+      ```
+</Steps>
+
+## Rendering CloudCannon content
+
+Use Astro's Content Collections API to [query and display your posts and collections](/en/guides/content-collections/#querying-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.
+
+```astro {4}
+---
+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](/en/guides/content-collections/#rendering-body-content):
+
+```astro {4-5}
+---
+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](/en/guides/content-collections/).
+
+## Deploying CloudCannon + Astro
+
+To deploy your website, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.
+
+## Configure Visual Editing
+
+CloudCannon's [Visual Editor](https://cloudcannon.com/documentation/articles/the-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](https://cloudcannon.com/documentation/guides/set-up-visual-editing/) (also available in your Site Dashboard). This will show you how to define [editable regions](https://cloudcannon.com/documentation/guides/set-up-visual-editing/an-overview-of-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:
+
+```html
+<p>By: <editable-text data-prop="author">{author}</editable-text></p>
+```
+
+### Visual Editing with components
+
+CloudCannon allows you to [define Component Editable Regions](https://cloudcannon.com/documentation/guides/set-up-visual-editing/visual-editing-for-components/) for live re-rendering of Astro components in the Visual Editor. This gives you the same interactive editing experience for your Astro components.
+
+<Steps>
+1. Install the [`@cloudcannon/editable-regions`](https://github.com/CloudCannon/editable-regions) package.
+
+    <PackageManagerTabs>
+      <Fragment slot="npm">
+      ```shell
+      npm install @cloudcannon/editable-regions
+      ```
+      </Fragment>
+      <Fragment slot="pnpm">
+      ```shell
+      pnpm add @cloudcannon/editable-regions
+      ```
+      </Fragment>
+      <Fragment slot="yarn">
+      ```shell
+      yarn add @cloudcannon/editable-regions
+      ```
+      </Fragment>
+    </PackageManagerTabs>
+
+2. Add the `editableRegions` integration to your Astro config:
+
+    ```js title="astro.config.mjs" ins={2} ins="editableRegions()"
+    import { defineConfig } from 'astro/config';
+    import editableRegions from "@cloudcannon/editable-regions/astro-integration";
+
+    export default defineConfig({
+      // ...
+      integrations: [editableRegions()],
+      // ...
+    });
+    ```
+
+3. Follow [CloudCannon's instructions to register your components](https://cloudcannon.com/documentation/guides/set-up-visual-editing/visual-editing-for-components/#register-your-components). This tells CloudCannon that those components should be bundled for client-side use in the Visual Editor.
+
+4. 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:
+
+    ```astro title="src/components/CTA.astro"
+    ---
+    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>
+
+    ```
+</Steps>
+
+:::tip
+Also see CloudCannon's [Astro Bookshop integration](https://cloudcannon.com/blog/how-cloudcannons-live-editing-works-with-astro-and-bookshop/) that allows you to add a `bookshop:live` directive to mark any component in your Astro template for live editing. It also allows you to configure live-editable [CloudCannon Snippets](https://cloudcannon.com/documentation/articles/what-is-a-snippet/) for visual editing and page building with components, including in your MDX Markdown content.
+:::
 
 ## Official Resources
 
+- [CloudCannon: The Astro CMS](https://cloudcannon.com/astro-cms/)
 - [Astro Starter Template](https://cloudcannon.com/templates/astro-starter/)
-- [Astro Multilingual Starter Template](https://cloudcannon.com/templates/astro-multilingual-starter/)
-- [Astro Starter Guide](https://cloudcannon.com/documentation/guides/astro-starter-guide/)
-- [Bookshop & Astro Guide](https://cloudcannon.com/documentation/guides/bookshop-astro-guide/)
-- [Astro Beginner Tutorial Series](https://cloudcannon.com/tutorials/astro-beginners-tutorial-series/)
+- Video: [Getting started with Astro and CloudCannon CMS: WYSIWYG blogging](https://www.youtube.com/watch?v=VCbZV-SCr20)
 - Blog: [How CloudCannon’s live editing works with Astro and Bookshop](https://cloudcannon.com/blog/how-cloudcannons-live-editing-works-with-astro-and-bookshop/)
-- Blog: [Out-of-this-world support for all Astro users](https://cloudcannon.com/blog/out-of-this-world-support-for-all-astro-users/)
+- [Bookshop & Astro Guide](https://cloudcannon.com/documentation/guides/bookshop-astro-guide/)
 
 ## Community Resources 
 
-- [CloudCannon announces official support for Astro](https://astro.build/blog/astro-cloudcannon-support/)
-
-## Themes
-
-<Grid>
-    <Card title="Sendit" href="https://astro.build/themes/details/sendit/" thumbnail="sendit.png"/>
-</Grid>
+- Video: [Astro CMS for Visual Editing: Getting Started with CloudCannon](https://www.youtube.com/watch?v=YcH53e1YamE)