Refresh CloudCannon CMS guide

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

@@ -9,27 +9,305 @@ 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 } 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. 
+
+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.
+
+### Mapping Astro collections to CloudCannon collections
+
+You can use CloudCannon as your Astro CMS even if you are not using content collections, but Astro's content collections are the best way to manage related content in any Astro project, providing type-safety, autocomplete, content-focused APIs, and more. Therefore, following instructions will assume that you are using content collections.
+
+When using Astro's collections, you will need to ensure that the data properties of your CloudCannon entries match the Zod validation `schema` defined in your content collection. CloudCannon collections 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 `staff` collection in your CloudCannon Site Dashboard while having individually defined Astro content collections for `management`, `marketing`, and `engineering`, each with a different data shape.
+
+For each Astro collection, it is recommended to create a CloudCannon schema (blank template document for creating a new entry) that satisfies your Astro collection's Zod schema. Your Astro project will throw an error if any content collection entry does not conform to its Zod schema defined in `src/content.config.ts`. So, creating a template schema can ensure that any new documents created in CloudCannon will have the properties required by your content collection.
+
+However, creating a schema in CloudCannon is not required. If no schema is provided, then CloudCannon will use the most recent document available in its collection as the basis for creating a new entry.
+
+To create a CloudCannon schema based on an Astro content collection `schema` for blog posts written in Markdown:
+
+<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.mdx"
+      ---
+      title:
+      author:
+      date:
+      ---
+
+      ```
+4. In your Cloudflare configuration file, add the file path to your schema under the CloudCannon collection where you keep your blog posts. 
+
+      The following example adds the blog post schema to a CloudCannon `posts` collection that already has  defines an article, event, and announcement schema, and adds these to the collections in which each type of content is used:
+
+      ```yml title="cloudcannon.config.yaml"
+      collections_config:
+      posts:
+        schemas:
+          default:
+            path: .cloudcannon/schemas/post.md
+            name: Blog Post Entry
+      ```
+</Steps>
+
+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.mdx"
+---
+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, 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.yaml"
+collections_config:
+posts:
+  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:
+  schemas:
+    default:
+      path: .cloudcannon/schemas/announcement.md
+      name: New Staff Announcement
+```
+
+
+## Creating a new post
+
+<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 schemas as above, 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/
+        - posts/
+          - **my-first-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 First 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 [Bookshop](https://cloudcannon.com/blog/how-cloudcannons-live-editing-works-with-astro-and-bookshop/) which provides a component development workflow for static websites that supports live visual editing and page-building with Astro.
+:::
 
 ## 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)