Update Getting Started Guide

.cloudcannon/routing.json

@@ -61,6 +61,16 @@
       "to": "/contact/",
       "status": 301
     },
+    {
+      "from": "/documentation/developer-guides/getting-started-with-cloudcannon/group-files-into-collections/",
+      "to": "/documentation/developer-guides/getting-started-with-cloudcannon/create-your-cloudcannon-configuration-file/",
+      "status": 301
+    },
+    {
+      "from": "/documentation/developer-guides/getting-started-with-cloudcannon/tour-a-collection-browser/",
+      "to": "/documentation/developer-guides/getting-started-with-cloudcannon/tour-your-site/",
+      "status": 301
+    },
     {
       "from": "/documentation/articles/astro-starter-guide/",
       "to": "/documentation/guides/getting-started-with-cloudcannon/",

_data/docshots.yml

@@ -1 +1 @@
-source: main_7a98e60ce3b2b5dbd1380b21963584b2ed20198a
+source: main_d67e3d9186386148d8317261eba1bdd9bab5a306

_includes/styles/shortcodes.scss

@@ -1,5 +1,10 @@
 .c-docs-image {
   $c: &;
+  display: block;
+
+  &__wrapper {
+    display: block;
+  }
 
   &__image {
     max-height: 100%;
@@ -11,7 +16,9 @@
   }
 
   &--type-ui-snippet {
+    display: block;
     max-width: 1000px;
+    max-height: 600px;
     padding: 20px;
     border: 2px solid var(--border-subtle);
     border-radius: var(--border-radius);
@@ -20,7 +27,10 @@
     background: var(--color-cloud);
 
     #{$c}__image {
+      display: block;
       width: auto;
+      height: auto;
+      max-height: 560px;
       margin: 0 auto;
     }
   }
@@ -47,7 +57,9 @@
     }
 
     #{$c}__image {
+      display: block;
       width: 100%;
+      max-height: 80vh;
       margin: 0;
       border-radius: var(--border-radius-inner);
     }

cloudcannon.config.yml

@@ -110,7 +110,7 @@ _editables:
     bulletedlist: true
     code: true
     embed: true
-    format: "p h1 h2 h3 h4 h5 h6"
+    format: "p h2 h3"
     horizontalrule: true
     image_size_attributes: true
     italic: true

developer/articles/configure-your-first-build.mdx

@@ -21,7 +21,7 @@ Building on CloudCannon is optional; however, it is required for web hosting and
 
 To build through CloudCannon, you must configure any command line options and build system options required for your Site. You can do this by starting the *Set up Visual Editing* or *Host your website on the Internet* in-app guides.
 
-<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Dashboard-Configure-Build-Task" alt="A screenshot of the Configure your Site's build settings task shows the Configure your build button." title="The Configure Site Build task" type="ui-snippet"/>
+<comp.DocShot docshot_key="CloudCannon-Documentation-Configure-Build-Task" alt="A screenshot of the Configure your Site's build settings task shows the Configure your build button." title="The Configure Site Build task" type="ui-snippet"/>
 
 To configure your first Site build:
 

developer/guides/getting-started-with-cloudcannon/create-a-site.mdx

@@ -1,17 +1,17 @@
 ---
 _schema: default
 _uuid: 1f1d14c4-4ab6-4495-88fe-9ec1850c3a74
-_created_at: 2025-07-18T10:09:31.000Z
+_created_at: 2025-07-18T10:09:31Z
 details:
   title: Create a Site
   order: 4
   image: >-
     https://cc-dam.imgix.net/documentation/images/guides/getting-started/guide-thumbnails/CloudCannon-Getting-Started-Thumbnail-Universal.png
   description: Learn about Sites on CloudCannon and how to create your first Site.
-  start_nav_group: null
-  related_articles: null
+  start_nav_group:
+  related_articles:
 author_notes:
-  docshots: null
+  docshots: Added!
 ---
 A *Site* is where you see, edit, and review all your website files. *Sites* are core to your CloudCannon experience and are where you and your content teams will spend the majority of your time.
 
@@ -34,7 +34,7 @@ When you create a *Site*, CloudCannon first needs to sync your website files fro
 
 This guide will cover how to create a *Site* from files stored in a Git repository.
 
-## Create your first Site
+## Create your first *Site*
 
 Let's walk through how to authenticate your Git provider, select a repository and branch, name your *Site*, and sync your files. If you already have at least one *Site* on CloudCannon and are using this guide to create another, most of the instructions will be the same; however, some pages or UI may look different.
 
@@ -104,12 +104,12 @@ CloudCannon will begin syncing your files from your Git provider and open your *
 
 On your *Site Dashboard*, you'll see another in-app guide: *Getting Started with Editing*. This guide focuses on setting up the basics of your *Site.*
 
-<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Dashboard-Add-Files" alt="A screenshot of the Site Dashboard shows the Getting Started with Editing guide with a task to Add your Files." title="The Site Dashboard" type="screenshot"/>
+<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Dashboard-Add-Your-Files-Task" alt="A screenshot of the Site Dashboard shows the Getting Started with Editing guide with a task to Add your Files." title="The Site Dashboard" type="screenshot"/>
 
 The first task in the *Getting Started with Editing* in-app guide is to *Add your files*. As CloudCannon is already syncing your files from your Git repository, you should see an in progress message under this step. This process is usually quick, but it may take a few minutes for larger repositories.
 
-Once CloudCannon has finished syncing, this step of the guide will update and allow you to mark the task as complete.
+Once CloudCannon has finished syncing, you can click the *Next* button.
 
-<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Dashboard-Add-Your-Files-Task" alt="A screenshot of the Add your Files task from the Getting Started with Editing in-app guide shows the Mark as complete button." title="The Add your Files task" type="ui-snippet"/>
+<comp.DocShot docshot_key="CloudCannon-Documentation-Add-Your-Files-Task" alt="A screenshot of the Add your Files task from the Getting Started with Editing in-app guide shows the Next button." title="The Add your Files task" type="ui-snippet"/>
 
 In the next step of this guide, we'll look at your new *Site* and introduce you to some important UI.

developer/guides/getting-started-with-cloudcannon/create-your-cloudcannon-configuration-file.mdx

@@ -1,56 +1,115 @@
 ---
 _schema: default
 _uuid: 64f7c038-a63e-4a95-bd1e-f72f3bd92db6
-_created_at: 2025-07-18T10:13:36.000Z
+_created_at: 2025-07-18T10:13:36Z
 details:
   title: Create your CloudCannon Configuration File
-  order: 6
+  order: 5
   image: >-
     https://cc-dam.imgix.net/documentation/images/guides/getting-started/guide-thumbnails/CloudCannon-Getting-Started-Thumbnail-Universal.png
   description: >-
     Learn about the CloudCannon Configuration File, including what it does and
     how to make one.
-  start_nav_group: null
-  related_articles: null
+  start_nav_group:
+  related_articles:
 author_notes:
-  docshots: null
+  docshots: Added!
 ---
 The next task in the *Getting Started with Editing* in-app guide is to *Create your CloudCannon Configuration File*.
 
-<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Dashboard-No-Config" alt="A screenshot of the Site Dashboard shows the Getting Started in-app guide with a task to create your CloudCannon Configuration File." title="The Site Dashboard" type="screenshot"/>
+<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Dashboard-Create-Config-File-Task" alt="A screenshot of the Site Dashboard shows the Getting Started in-app guide with a task to create your CloudCannon Configuration File." title="The Site Dashboard" type="screenshot"/>
 
 The *CloudCannon Configuration File* is the heart of your CloudCannon experience, allowing you to customize the functionality and appearance of your *Site*. You can configure your *Site Navigation*, Editing Interfaces, file appearance in the app, how CloudCannon adds new files, and more by adding formatted content to your *Configuration File*.
 
 As we go through the later steps of this guide, we'll add more to our *Configuration File*. Let's create one.
 
-## Initial content for the *CloudCannon Configuration File*
-
 Click the *\+ Create my Configuration File* button in your in-app guide under the *Create your CloudCannon Configuration File* task. CloudCannon will open the *Create my Configuration File* modal.
 
-<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Dashboard-Create-Config-File-Task" alt="A screenshot of the Create your CloudCannon Configuration File task from the Getting Started in-app guide shows the Create my Configuration File button." title="The Create a Configuration File task" type="ui-snippet"/>
+<comp.DocShot docshot_key="CloudCannon-Documentation-Create-Config-File-Task" alt="A screenshot of the Create your CloudCannon Configuration File task from the Getting Started in-app guide shows the Create my Configuration File button." title="The Create a Configuration File task" type="ui-snippet"/>
+
+The *CloudCannon Configuration File* is stored at the root of your website directory by default and can be YAML or JSON. When you answer the questions in this modal, CloudCannon will create the `/cloudcannon.config.yml` file in the root of your repository.
+
+## Select your *Static Site Generator*
+
+<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Dashboard-Create-Config-File-Modal" alt="A screenshot of the Create my Configuration File modal shows a dropdown for selecting your SSG and a checkbox for Use a custom source." title="The Create my Configuration File modal" type="screenshot"/>
+
+To start with, CloudCannon needs to know which <comp.GlossaryTerm term="/user/glossary/s/ssg.yml">Static Site Generator</comp.GlossaryTerm> your *Site* uses. An SSG is a tool for generating a static HTML website from your files. CloudCannon supports various SSGs, from Astro, Eleventy, and Hugo to Jekyll, MkDocs, and Lume. You can choose whichever SSG is appropriate for your website files.
+
+CloudCannon will use the information found in your files to suggest an *SSG*. You can click on the *Use* button under the right side of the *Static Site Generator* dropdown to populate it with CloudCannon's suggestion, or select an option from the list of CloudCannon's supported *SSGs*.
+
+At the bottom of the *Create my Configuration File* modal is the *Preview* button. Clicking this button will show you a preview of the initial content of your *CloudCannon Configuration File*.
+
+<comp.DocShot docshot_key="CloudCannon-Documentation-Create-Config-File-Modal-Code" alt="A screenshot of the Create my Configuration File modal shows the initial content CloudCannon will add to your Configuration File." title="The Create my Configuration File modal" type="ui-snippet"/>
+
+## Select your *Source Folder* (optional)
+
+<comp.DocShot docshot_key="CloudCannon-Documentation-Create-Config-File-Modal-Custom-Source" alt="A screenshot of the Create my Configuration File modal shows a checkbox for Use a custom source and a text field for Source Folder." title="The Create my Configuration File modal" type="ui-snippet"/>
+
+CloudCannon needs to know the base path for your SSG source files relative to the root of your directory, called the *Source Folder*. Most websites use the root of their repository as the *Source Folder*.
+
+However, if your source is nested in your repository (such as if you have a mono-repo), you should check the *Use a custom source* box and enter the file path in the *Source Folder* text field.
+
+## Select your *Collections*
+
+Click the *Next* button on the bottom right of the *Create my Configuration File* modal.
+
+<comp.DocShot docshot_key="CloudCannon-Documentation-Create-Config-File-Modal-Add-First-Collections" alt="A screenshot of the Create my Configuration File modal shows a tree structure of potential Collections detected in your files." title="The Create my Configuration File modal" type="ui-snippet"/>
+
+On the next page of the modal, CloudCannon asks you to select your *Collections*. A <comp.GlossaryTerm term="/user/glossary/c/collection.yml">Collection</comp.GlossaryTerm> is a group of files you want to edit in CloudCannon, and will match a folder in your *Git Repository* (e.g., a folder of pages, blog posts, product descriptions, or data files).
+
+Once you select your *Collections,* they will appear in your *Site Navigation* for easy access. On the right of the modal, you can see a preview of the default name and icon CloudCannon will assign to each *Collection* (you can change these later), along with the number of content files each *Collection* will contain.
+
+<comp.DocShot docshot_key="CloudCannon-Documentation-Create-Config-File-Modal-Detected-Collection" alt="A screenshot of a detected Collection in the Create my Configuration File modal." title="A Detected Collection" type="ui-snippet"/>
+
+CloudCannon will automatically detect which folders in your *Git Repository* contain content files and suggest that you turn these into *Collections*. By default, suggested *Collections* are checked in the *Create my Configuration File* modal. Alternatively, you can deselect any folders you don't want to edit in CloudCannon using the checkbox.
+
+<comp.Notice info_type="info">
+  **What happens when you select one** ***Collection*** **nested inside of another?**
+
+  Files can only belong to one *Collection* at a time. If you select two *Collections*, one nested inside another, the files will appear in the *Collection* with the most specific *Path*.
 
-The *CloudCannon Configuration File* is stored at the root of your website directory by default and can be YAML (or JSON). When you answer the questions in this modal, CloudCannon will create the `/cloudcannon.config.yml` file in the root of your repository.
+  Let's walk through an example.
 
-<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Dashboard-Create-Config-File-Modal" alt="A screenshot of the Create my Configuration File modal shows a text field for selecting your SSG and a checkbox for Source Folder." title="The Create my Configuration File modal" type="screenshot"/>
+  <comp.DocsImage path="https://cc-dam.imgix.net/documentation/images/guides/getting-started/2025-09/CloudCannon-Documentation-Collection-File-Structure.png" alt="An illustration of a file structure shows a blog folder with two nested files and a nested authors folder, which also has two nested files." title="An example file structure" type="ui-snippet"/>
 
-To start with, CloudCannon needs to know two key pieces of information about your *Site*: which Static Site Generator (SSG) you are using and where your *Source Folder* is in your repository.
+  Assume you have an `authors` folder nested in your `blog` folder (i.e., `/blog/authors/`). The `authors` folder contains non-output data files with profile information about your various blog authors. In addition to the `authors` folder, the `blog` folder also contains all your output blog files. In this case, both the `authors` and `blog` folders could be *Collections*.
 
-An SSG is a tool for generating a static HTML website from your files. CloudCannon supports various SSGs, from Astro, Eleventy, and Hugo to Jekyll, MkDocs, and Lume. You can choose whichever SSG is appropriate for your website files.
+  If you only add the "Blog" *Collection* with the path `/blog/`, all your output blog files will belong to this *Collection*, but so will all the data files inside `/blog/authors/`. All these files will appear as a sub-folder in your Blog *Collection Browser*.
 
-CloudCannon will use the information found in your files to suggest an SSG. You can click on the *Use* button next to the suggested SSG to select it, or use an option from the *Static Site Generator* dropdown.
+  Adding the "Blog" *Collection* and the "Authors" *Collection* will separate these files, keeping your output blog files in one *Collection Browser* and your non-output data files in another.
+</comp.Notice>
 
-The *Source Folder* defines the base path for your SSG source files relative to the root of your directory. Most websites use the root of their repository as the *Source Folder*. However, if your source folder is nested in your repository (such as if you have a mono-repo), you should check the *Use custom source* box and enter the file path in the *Source Folder* text field.
+Like the previous section of the *Create my Configuration File* modal, you can click the *Preview* button in the bottom right to preview the contents you are adding to your *CloudCannon Configuration File*.
 
-At the bottom of the *Create my Configuration File* modal is the *Show changes* button. Clicking this button will show you a preview of the initial content of your *CloudCannon Configuration File*. This content is based on your answers to the above questions and converted to YAML.
+Here's an example of what that configuration code might look like for a *Collection*:
 
-<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Dashboard-Create-Config-File-Modal-Code" alt="A screenshot of the Create my Configuration File modal shows the initial content CloudCannon will add to your Configuration File." title="The Create my Configuration File modal" type="screenshot"/>
+<comp.MultiCodeBlock language="YAML" translate_into={["json"]} source="cloudcannon.config.yml">
+``````````
+collections_config___1___:
+  news___2___:
+    path___3___: /blog/news/
+    icon___4___: breaking_news
+``````````
+<comp.Annotation number="1">
+  All *Collections* are defined under the `collections_config` key in your *CloudCannon Configuration File*.
+</comp.Annotation>
+<comp.Annotation number="2">
+  The *Key* for this *Collection* is `news`. All the configuration for this *Collection* is stored nder this *Key*.
+</comp.Annotation>
+<comp.Annotation number="3">
+  The *Path* for this *Collection* is `/blog/news/`, telling CloudCannon where to find the *Collection* files in your repository.
+</comp.Annotation>
+<comp.Annotation number="4">
+  The *Icon* for this *Collection* is `breaking_news`.
+</comp.Annotation>
+</comp.MultiCodeBlock>
 
-Click the *Create my Configuration File* button at the bottom of the modal. CloudCannon will add `cloudcannon.config.yml` to the root of your repository. Once you have returned to your *Site Dashboard*, you can mark the *Create your CloudCannon Configuration File* task as complete.
+When you are happy with your selection, click the *Create my Configuration File* button at the bottom of the modal, and CloudCannon will add `cloudcannon.config.yml` to the root of your repository. Your *Collections* will appear in the *Site Navigation.*
 
 Congratulations! You've made your first change to your website content: adding a file. You might notice that the *Save* button in the top right now has a red "1" notification. This indicates that you have made a change to one file. Don't click the *Save* button just yet—we'll talk about saving changes to your *Site* in the [save your Configuration File](/documentation/developer-guides/getting-started-with-cloudcannon/save-your-configuration-file/) step of this guide.
 
-<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Header-Tools" alt="A screenshot of the Site Header tools shows the Avatar List, Configuration Mode toggle, and the Save button with one unsaved change." title="The Site Header tools" type="ui-snippet"/>
+<comp.DocShot docshot_key="CloudCannon-Documentation-Site-Header-Tools-New-Config" alt="A screenshot of the Site Header tools shows the Avatar List, Configuration Mode toggle, and the Save button with one unsaved change." title="The Site Header tools" type="ui-snippet"/>
 
 You might also notice a new UI element next to the *Save* button. This is the *Configuration Mode switch*. Now that we have a *Configuration File*, we can use *Configuration Mode* to customize our *Site* and store our preferences.
 
-In the next step of this guide, we'll use *Configuration Mode* to group our files into user-friendly *Collections*.
+In the next step of this guide, we'll look at your new *Site* and introduce you to some important UI.