What is the CloudCannon link protocol?

The CloudCannon link protocol is a URL scheme, written cloudcannon:, that CloudCannon recognizes in links you author. Where an ordinary link points at a page on your Site, a CloudCannon link opens a destination inside CloudCannon instead.

You write the protocol in several places — an <a> element on your previewed page, a binding attribute, a comment in the Data Editor — and each place reads the same syntax. What differs is which parts of that syntax a given place supports, covered in Where the protocol works below.

The two forms#

A CloudCannon link takes one of two forms, and a single link cannot combine them.

cloudcannon: followed by a path opens that destination in the app. CloudCannon resolves the path against the Site you have open, so dashboard opens its Site Dashboard.

cloudcannon: followed by # and a slug opens the field behind a value in the file you are editing. The # has to come directly after cloudcannon: — CloudCannon reads a link as a slug only when the # is the first character after the scheme, and treats anything else as a path.

<a href="cloudcannon:dashboard">Open the Site Dashboard</a> 

<a href="cloudcannon:#title">Edit the title</a> 

Naming a value with a slug#

A slug names a value by its position in your data. Start at the root of the file's structure and name each step toward the value you want, separating objects and properties with a dot. Denote an array item with a zero-based index in square brackets.

<a href="cloudcannon:#title">The title of the current file</a>

<a href="cloudcannon:#seo.title">The title inside the seo object</a>

<a href="cloudcannon:#people[0]">The first item in an array named people</a> 

<a href="cloudcannon:#people[0].title">The title of that first item</a>

Where a key contains a dot, an opening bracket, or a closing bracket, escape that character with a backslash so CloudCannon treats it as part of the key rather than as a separator.

<a href="cloudcannon:#meta.og\.title">A key named og.title inside meta</a>

Naming a path#

A path names a destination in CloudCannon the way the app's own URLs do, relative to your Site. In a URL like https://app.cloudcannon.com/123/editor#sites/456/dashboard, the part after the Site ID is the path, so the link is cloudcannon:dashboard.

Paths that begin with collections/ are the exception, because the two places that accept them resolve them differently. See Where the protocol works below before writing one.

Where the protocol works#

Four places in CloudCannon read the protocol.

• Links on your previewed page — an <a> element whose href uses the scheme. For more information, please read our documentation on what Editor Links are.
• Binding attributes — data-cms-bind and data-cms-editor-link take the same syntax as an attribute value rather than an href. For more information, please read our documentation on what Visual Data Bindings are.
• Comments in the Data Editor — a comment on an input, a block, or your Site Dashboard README can carry a CloudCannon link in its Markdown. For the README case, please read our documentation on what the Site Dashboard README is.
• Add options — add_options entries accept a CloudCannon link in href. This is a legacy form, and new configuration uses a plain relative link instead. For more information, please read our documentation on configuring the Add button in collections.

What differs between places

The syntax above reads the same everywhere, but four behaviors do not carry across:

• Where a field opens — A link on your previewed page opens a Data Panel floating over the page, and the data-cms-editor-link-style attribute can highlight the field in the sidebar instead. A link in a comment always opens a Data Panel, and the attribute has no effect there.
• Paths beginning with collections/ — On your previewed page, the segment after collections/ is the path a Collection reads from in your repository. In a comment, it is the Collection key, as the app's own URL writes it.
• Links to CloudCannon itself — In a comment, cloudcannon:!home opens your Organization home and cloudcannon:!support opens the support widget. No other ! path is treated specially, and the preview does not recognize either.
• Appending to an array — A slug ending in [+] adds an item to the end of that array, and only a binding attribute supports it. As an href, it names a field that does not exist.