Refresh CloudCannon CMS guide

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

@@ -9,27 +9,270 @@ 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.
+
+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.
+
+### 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>
+
+## 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 and pull new changes from git. 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 title="src/pages/blog.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 title="src/pages/blog/my-first-post.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)