We would like to announce the redesign of our Documentation pages this year. This includes all elements of the UX/UI to improve the appearance and functionality of the docs.
Not everyone wants to involve our support team when they have a question or a problem (even though they’re the greatest ). At CloudCannon, we value your ability to resolve your own issues, in your own time, with complete confidence. Better docs mean quicker problem-solving, more resources when you are trying to support your team or clients, and an easier time onboarding if you are a brand-new customer.
With this in mind, we’ll use this thread to keep you up to date with our project. We’ll also create other threads to ask specific questions about the project, such as “How would you prefer to search for configuration keys?” (see that thread here).
How can you get involved?
Your feedback is really important to us. In this thread, we would love if you could let us know:
What do you like and dislike about our current Documentation?
What areas of the docs do you rely on the most?
Is there anything you think we are missing?
Are there any examples of good documentation you use often?
This is great! I’m someone who will always go try to figure it out first, and reach out to support as a last resort.
A while ago I came across this documentation framework. I haven’t had the time to implement for my own things, but I think it is worth considering for this project.
Something that I don’t think was documented well enough is template strings (I don’t think this is what they are called but that is where I found them in the documentation) and how they can be used for input configuration. If this is an obvious industry standard thing, maybe mentioning the name of the system, I don’t know if its a standard or something came up with.
For example. I didn’t know that we could reference boolean values from the frontmatter in the inputs until I saw the banner in the Alto template. Notice the !enable_banner in the input configuration.
enable_banner: false
html: <p>This banner is completely optional, and can be shown until a set date!</p>
id: alto-banner-1
show_until: 2024-07-27T00:00:00Z
color_group: primary
colorFromGroup: primary
_inputs:
enable_banner:
type: switch
html:
type: html
label: Banner Content
hidden: '!enable_banner'
id:
type: text
label: Unique ID
hidden: '!enable_banner'
comment: >-
Prevents repeated display for users who close the banner, changing ID
resets for all.
show_until:
type: date
comment: Date to stop showing the banner
Another example is how to setup values that happen to be nested in a data file. Notice the data.listings.filtering[*] I took a guess at this working, but wasn’t a specific documentation example. Again, maybe its industry standard thing I don’t know the name of.
# Metadata about this component, to be used in the CMS
spec:
structures:
- content_blocks
- extra_blocks
label: "ListingsAll"
description:
icon:
tags: []
# Defines the structure of this component, as well as the default values
blueprint:
content:
sectionId:
filterCollection:
styles:
color_group: primary
# Overrides any fields in the blueprint when viewing this component in the component browser
preview:
# Any extra CloudCannon inputs configuration to apply to the blueprint
_inputs:
filterCollection:
type: select
options:
allow_empty: false
values: data.listings.filtering[*]
value_key: id
text_key: filterCollectionName
Funnily enough, we’ve already committed to using Divio/Diataxis for our documentation content. You may have noticed an increase in “What is…” articles and key Reference articles. This is in direct response to Diataxis revealing holes in our documentation. I’m glad we’re on the same page.
The 2025 Documentation Redesign is more about the UX/UI of our documentation pages. But I’m always open to feedback about pages or concepts where you think the content needs work. The Documentation Feedback category in this community is a great place to post (I’ll be in here every day ).
On your comment about template strings
You’re right — the template string docs need work. I’ll make a ticket improve the clarity of the language we use there.
In the two examples you give, values: data.listings.filtering[*] is a JSONPath selector while hidden: '!enable_banner' is an expression.
The hidden key for Inputs accepts both boolean and string values. This key is an example of our early implementation of CloudCannon’s expression engine, and we’ll probably update it in the future.
We recently started supporting JSONPath selectors ([*]) for strings (data.listings.filtering) in the values key (here’s a changelog) rather than the single level references (e.g. collections.posts or data.listings ). This allows you to dig deeper, and filter into these datasets. We touch on this concept in the Filters section of our Select Input article, but this feature is not well documented yet
I want to make better Reference documentation
I’m committed to making more docs like our key Reference pages so that this kind of information never comes as a surprise to the user. The docs should describe the following for every configuration key:
The key name
The key definition
Where and how you should use a key in your CloudCannon configuration file
Links to relevant parent keys and subkeys
Valid values for a key
Real examples of how to use that key
In the 2025 Redesign, I want to give key Reference pages their own home (I talk about that in this thread) so it’s easier to search for configuration examples. If you have any thoughts about that, I’d love to hear them!
). At CloudCannon, we value your ability to resolve your own issues, in your own time, with complete confidence. Better docs mean quicker problem-solving, more resources when you are trying to support your team or clients, and an easier time onboarding if you are a brand-new customer.
came up with.
).
nice investigative work,