CloudCannon Development Guide

Useful Resources

We use Hugo for our static site generator. See Hugo’s documentation.
Our CMS is CloudCannon. Make sure to read CloudCannon’s documentation.
We use Bookshop to add components to pages in CloudCannon. See the Hugo Bookshop Reference Guide.
CloudCannon also has a very useful YouTube channel.

Getting Started

In order to develop themes for CloudCannon, you should learn Hugo. Once you have Hugo set up on your computer, clone your repo to a folder that you want to contain all CloudCannon themes e.g. sites/cloudcannon_themes. Once you’ve cloned your repo, cd into your project directory and run npm install. You should then be able to run hugo serve, which will fire up a local server. You can then view your site at localhost:1313, edit your theme and/or content, and push edits back to your repo, etc.

DSv3 Base Theme

All themes import our WVU DSv3 Base Theme as a Hugo module. This is where the Sass and default layouts for every WVU Hugo site live. See Hugo’s directory structure for reference. You do not need to ever touch this theme. We’re just posting here for reference. However, you can overwrite layouts e.g. baseof.html or partials e.g. partials/masthead.html in your own theme.

Your Site’s Theme

Your theme will contain several files of note:

Hugo config files, found in /config. This is where you define your site title, taxonomies, modules to import, etc. See Hugo’s configuration docs.
A CloudCannon config file, found in the project root cloudcannon.config.yml. This is where you define collections in CloudCannon, and configure inputs, data, structures, etc. See CloudCannon’s configuration docs.
CloudCannon schemas, found in .cloudcannon/schemas. This is where you define templates for various pages/collections so CloudCannon knows what inputs to populate when adding a new page, collection item, etc. See CloudCannon’s schema docs.
Data files, under data. This is where you can store collection data.
Some test content. By default, we have included some example content e.g. a person in your content/people folder. Keep at least one example file in each folder, if example files exist. If you delete them all, this might cause an error when building your site.

Shared Component Library

All sites in CloudCannon use a shared component library. These are “Bookshop” components. These components are mounted in CloudCannon using CloudCannon’s site mounting feature.

Note, in addition to using our shared Bookshop components, you can create custom templates with “editable regions” (similar to CleanSlate, if you’ve worked with CleanSlate before).

Creating Custom Bookshop Components

Add new components to the component-library/components directory of your site. Each component should be in its own folder and contain both a {name-of-component}.bookshop.yml file and a {name-of-component}.hugo.html file, per the Hugo Bookshop Reference Guide.

Note, you cannot currently “override” shared Bookshop components. If you make a custom component that is similar to a shared component, give it a unique name to differentiate it from the shared component. Note, it is possible to build logic into the base theme to use a local version and not display the shared component in CloudCannon, but we haven’t implemented that feature yet.

To get components to show along with shared components in the CloudCannon UI, make sure to add the correct structure to your component’s config file. Add them to your component’s config file like this:

  spec:
    structures:
      - content_blocks

Here are the structures used to add components to pages:

content_blocks: These are components you can add to a guide page.
detail_blocks: These are components you can add to the center column of a detail page.
detail_sidebar_blocks: These are components you can add to the sidebar of a detail page.
column_blocks: These are nested components you can add to a large column of a layout component.
column_blocks_sm: These are nested components you can add to a small column of a layout component.
article_blocks: These are components you can add to the center column of an article.
photo_essay_blocks: These are components you can add to the center column of a photo-essay.

Tips When Creating Custom Bookshop Components for CloudCannon

When creating your own components, make sure you validate certain inputs to both limit the size of images the user uploads, and force the user to upload them to our CloudCannon DAM. Here is an example for an image input:
```
  image:
    type: image
    options:
      allowed_sources:
        - ccdam
      width: 1920
      height: 1080
```
The value ccdam in the above example is defined in your Site Settings in CloudCannon. It should never change. We use a DAM to reduce the size of our Bitbucket repos and increase build times. If you forget to configure image inputs correctly, and as a result users upload large images to your site, we will make you create a new repo that is configured correctly, and you will have to add the images to the DAM. YOU HAVE BEEN WARNED.
Hide complex Hugo logic from CloudCannon’s visual editor. As a general rule, you can assign values to variables, display values, use if logic, and use range to loop through arrays. Other logic that is commonly used, for example image processing, and counters within range loops, will slow down editing in CloudCannon. Logic can be “hidden” from CloudCannon’s editor by wrapping the logic with {{- if not site.Params.env_bookshop_live -}} .. {{- end -}}.
The same is true for “dynamic” components. For example, if you are creating a component that aims to pull in data from a collection, and display that data on your page, this will cause a significant lag when editing content. Any logic in your components that pulls in content dynamically should also be wrapped with {{- if not site.Params.env_bookshop_live -}} .. {{- end -}}. You will not be able to see this content in CloudCannon’s visual editor, but it will show when your site builds and can be viewed at your preview site.

Active Campus Alert