Migrating to preview options

Last modified: August 21st, 2024

Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.

Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.

How you configure previews in CloudCannon has changed. We recommend updating, but the previous configuration will continue to work. There’s now a consolidated key called preview that encompasses our previous keys:

  • text_key
  • text
  • subtext_key
  • subtext
  • icon_key
  • icon
  • image_key
  • image
  • image_size
  • preview_image
  • description

As our configuration has grown, many of these keys were used inconsistently across different locations. We now offer a single option called preview that contains each of these options in a cascading process.

You can now define more than one option value for each preview option. Each option value is processed in order until a data value is found.

This is used in a number of places so far:

  1. Hugo Shortcodes (Snippets)
  2. Snippet Picker
  3. Structures inside Array inputs
  4. Structure Picker
  5. Select-style inputs
  6. Object inputs
  7. Non-structure items inside Array inputs

Examples#

Here are a number of examples to show the difference before and after migrating.

Collection items#

Changing how collection items look in the collection file list:

cloudcannon.config.yml (legacy)
copied
collections_config:
  posts:
    text_key: heading
    subtext_key: author
    icon: event_available
    image_key: thumbnail
    image_size: contain
cloudcannon.config.yaml
copied
collections_config:
  posts:
    icon: event_available
    preview:
      text_key:
        - key: heading
      subtext_key:
        - key: author
      icon: event_available
      image:
        - key: thumbnail
cloudcannon.config.json
copied
{
  "collections_config": {
    "posts": {
      "icon": "event_available",
      "preview": {
        "text_key": [
          {
            "key": "heading"
          }
        ],
        "subtext_key": [
          {
            "key": "author"
          }
        ],
        "icon": "event_available",
        "image": [
          {
            "key": "thumbnail"
          }
        ]
      }
    }
  }
}
cloudcannon.config.cjs
copied
module.exports = {
  collections_config: {
    posts: {
      icon: "event_available",
      preview: {
        text_key: [
          {
            key: "heading"
          }
        ],
        subtext_key: [
          {
            key: "author"
          }
        ],
        icon: "event_available",
        image: [
          {
            key: "thumbnail"
          }
        ]
      }
    }
  }
};

Changing how a collection item with a schema appears in the collection file list:

cloudcannon.config.yml (legacy)
copied
collections_config:
  posts:
    schemas:
      default:
        path: schemas/post.md
      news:
        path: schemas/news-post.md
        text_key: heading
        icon: newspaper
        image_key: cover_image
        image_size: cover
cloudcannon.config.yaml
copied
collections_config:
  posts:
    schemas:
      default:
        path: schemas/post.md
      news:
        path: schemas/news-post.md
        preview:
          text:
            - key: heading
          icon: newspaper
          gallery:
            image:
              - key: cover_image
            fit: cover
cloudcannon.config.json
copied
{
  "collections_config": {
    "posts": {
      "schemas": {
        "default": {
          "path": "schemas/post.md"
        },
        "news": {
          "path": "schemas/news-post.md",
          "preview": {
            "text": [
              {
                "key": "heading"
              }
            ],
            "icon": "newspaper",
            "gallery": {
              "image": [
                {
                  "key": "cover_image"
                }
              ],
              "fit": "cover"
            }
          }
        }
      }
    }
  }
}
cloudcannon.config.cjs
copied
module.exports = {
  collections_config: {
    posts: {
      schemas: {
        default: {
          path: "schemas/post.md"
        },
        news: {
          path: "schemas/news-post.md",
          preview: {
            text: [
              {
                key: "heading"
              }
            ],
            icon: "newspaper",
            gallery: {
              image: [
                {
                  key: "cover_image"
                }
              ],
              fit: "cover"
            }
          }
        }
      }
    }
  }
};

Object and Array inputs#

Changing how an object input appears in the Data Editor before opening:

cloudcannon.config.yml (legacy)
copied
seo:
  title: About us
  description: A longer description of the page that is all about us.
  image: /uploads/seo-cover.png
_inputs:
  seo:
    text_key: title
    subtext_key: description
    icon: search
    image_key: image
cloudcannon.config.yaml
copied
seo:
  title: About us
  description: A longer description of the page that is all about us.
  image: /uploads/seo-cover.png
_inputs:
  seo:
    preview:
      text:
        - key: title
      subtext:
        - key: description
      icon: search
      image:
        - key: image
cloudcannon.config.json
copied
{
  "seo": {
    "title": "About us",
    "description": "A longer description of the page that is all about us.",
    "image": "/uploads/seo-cover.png"
  },
  "_inputs": {
    "seo": {
      "preview": {
        "text": [
          {
            "key": "title"
          }
        ],
        "subtext": [
          {
            "key": "description"
          }
        ],
        "icon": "search",
        "image": [
          {
            "key": "image"
          }
        ]
      }
    }
  }
}
cloudcannon.config.cjs
copied
module.exports = {
  seo: {
    title: "About us",
    description: "A longer description of the page that is all about us.",
    image: "/uploads/seo-cover.png"
  },
  _inputs: {
    seo: {
      preview: {
        text: [
          {
            key: "title"
          }
        ],
        subtext: [
          {
            key: "description"
          }
        ],
        icon: "search",
        image: [
          {
            key: "image"
          }
        ]
      }
    }
  }
};

Changing how a non-structure item within an array input appears in the Data Editor before opening:

cloudcannon.config.yml (legacy)
copied
quotes:
  - message: Great product!
    author: Jane
    image: /uploads/jane.png
  - message: Highly recommended.
    author: John
    image: /uploads/john.png
_inputs:
  quotes:
    text_key: message
    subtext_key: author
    icon: format_quote
    image_key: image
cloudcannon.config.yaml
copied
quotes:
  - message: Great product!
    author: Jane
    image: /uploads/jane.png
  - message: Highly recommended.
    author: John
    image: /uploads/john.png
_inputs:
  quotes:
    preview:
      text:
        - key: message
      subtext:
        - key: author
      icon: format_quote
      image:
        - key: image
cloudcannon.config.json
copied
{
  "quotes": [
    {
      "message": "Great product!",
      "author": "Jane",
      "image": "/uploads/jane.png"
    },
    {
      "message": "Highly recommended.",
      "author": "John",
      "image": "/uploads/john.png"
    }
  ],
  "_inputs": {
    "quotes": {
      "preview": {
        "text": [
          {
            "key": "message"
          }
        ],
        "subtext": [
          {
            "key": "author"
          }
        ],
        "icon": "format_quote",
        "image": [
          {
            "key": "image"
          }
        ]
      }
    }
  }
}
cloudcannon.config.cjs
copied
module.exports = {
  quotes: [
    {
      message: "Great product!",
      author: "Jane",
      image: "/uploads/jane.png"
    },
    {
      message: "Highly recommended.",
      author: "John",
      image: "/uploads/john.png"
    }
  ],
  _inputs: {
    quotes: {
      preview: {
        text: [
          {
            key: "message"
          }
        ],
        subtext: [
          {
            key: "author"
          }
        ],
        icon: "format_quote",
        image: [
          {
            key: "image"
          }
        ]
      }
    }
  }
};

Structures#

Changing how a structure item appears when choosing a new one to add in the Data Editor:

cloudcannon.config.yml (legacy)
copied
_structures:
  gallery:
    style: modal
    values:
      - label: Image
        description: Full width image
        preview_image: https://example.com/image-screenshot.png
        image: /path/to/image.png
        icon: image
        text_key: caption
        subtext_key: image
        image_key: image
        image_size: cover
        tags:
          - Media
          - Asset
        value:
          image: /uploads/placeholder.png
          caption:
      - label: External link
        icon: link
        tags:
          - Media
        value:
          url:
          title:
cloudcannon.config.yaml
copied
_structures:
  gallery:
    style: modal
    values:
      - label: Image
        icon: image
        tags:
          - Media
          - Asset
        value:
          image: /uploads/placeholder.png
          caption: 
        preview:
          text:
            - key: caption
          icon: image
          subtext:
            - key: image
            - Full width image
          gallery:
            image:
              - key: image
              - /path/to/image.png
            fit: cover
        picker_preview:
          gallery:
            image: https://example.com/image-screenshot.png
      - label: External link
        icon: link
        tags:
          - Media
        value:
          url: 
          title:
cloudcannon.config.json
copied
{
  "_structures": {
    "gallery": {
      "style": "modal",
      "values": [
        {
          "label": "Image",
          "icon": "image",
          "tags": [
            "Media",
            "Asset"
          ],
          "value": {
            "image": "/uploads/placeholder.png",
            "caption": null
          },
          "preview": {
            "text": [
              {
                "key": "caption"
              }
            ],
            "icon": "image",
            "subtext": [
              {
                "key": "image"
              },
              "Full width image"
            ],
            "gallery": {
              "image": [
                {
                  "key": "image"
                },
                "/path/to/image.png"
              ],
              "fit": "cover"
            }
          },
          "picker_preview": {
            "gallery": {
              "image": "https://example.com/image-screenshot.png"
            }
          }
        },
        {
          "label": "External link",
          "icon": "link",
          "tags": [
            "Media"
          ],
          "value": {
            "url": null,
            "title": null
          }
        }
      ]
    }
  }
}
cloudcannon.config.cjs
copied
module.exports = {
  _structures: {
    gallery: {
      style: "modal",
      values: [
        {
          label: "Image",
          icon: "image",
          tags: [
            "Media",
            "Asset"
          ],
          value: {
            image: "/uploads/placeholder.png",
            caption: null
          },
          preview: {
            text: [
              {
                key: "caption"
              }
            ],
            icon: "image",
            subtext: [
              {
                key: "image"
              },
              "Full width image"
            ],
            gallery: {
              image: [
                {
                  key: "image"
                },
                "/path/to/image.png"
              ],
              fit: "cover"
            }
          },
          picker_preview: {
            gallery: {
              image: "https://example.com/image-screenshot.png"
            }
          }
        },
        {
          label: "External link",
          icon: "link",
          tags: [
            "Media"
          ],
          value: {
            url: null,
            title: null
          }
        }
      ]
    }
  }
};

Related Articles

Open in a new tab