Setup

This guide covers how to install CloudCannon Suite and use it with a Jekyll project.

Install prerequisites

First, make sure you have the right tools installed globally.

Node & npm

npm (Node Package Manager) is a useful JavaScript package manager. It is distributed alongside Node, a JavaScript runtime designed for building network applications.

To check if you have Node and npm installed, run these commands in your terminal:

$ node -v
$ npm -v

If either of these commands fail, follow the npm install guide and retry.

gulp-CLI

Installing the gulp CLI allows you to run the gulp command in your terminal.

$ npm install --global gulp-cli

You can confirm the installation worked with gulp -v.

Project structure

Once the prerequisites are installed, you can add the CloudCannon Suite to a Jekyll project. Using the prescribed file structure helps keep your projects organised and consistent.

Prepare source directory

A custom source directory keeps the root directory clean and free for configuration. Move all Jekyll source (including Gemfile and Gemfile.lock) to the src folder. You can do this with the following Bash commands:

$ mkdir src
$ mv `ls -A | grep -v src` ./src

If you don’t want to use the command line, this can be done in Finder/Explorer.

Create a package.json

Create a package.json in your project directory, if you don’t already have one. If you need help, run npm init, which will walk you through giving it a name, version, description, etc.

Add Dependencies

Open your package.json and add dependencies for Gulp and the CloudCannon Suite as follows:

"dependencies": {
     "gulp": "^4.0.0",
     "@cloudcannon/suite": "^2.0.0-rc6"
}

Install Packages

Run the npm install command in your project directory to install all the dependencies specified in your package.json.

Create a gulpfile

Create a file named gulpfile.js in your project directory, with the following content:

const gulp = require("gulp");
const suite = require("@cloudcannon/suite");

suite.dev(gulp);

Test your suite

Run gulp dev:install in your project directory. This runs bundle install for your site.

Next run gulp dev in your project directory to build and serve your site. See the Dev package for more information about this.

$ gulp dev
[19:14:48] Using gulpfile ~/Work/cloudcannon/suite/gulpfile.js
[19:14:48] Starting 'dev'...
[19:14:48] Starting 'dev:build'...
[19:14:48] $ bundle exec jekyll build --destination dist/site
Configuration file: src/_config.yml
            Source: src
       Destination: dist/src
 Incremental build: disabled. Enable with --incremental
      Generating...
                    done in 0.73 seconds.
 Auto-regeneration: disabled. Use --watch to enable.
[19:14:50] Finished 'dev:build' after 1.58 s
[19:14:50] Starting 'dev:watch'...
[19:14:50] Finished 'dev:watch' after 45 ms
[19:14:50] Starting 'dev:serve'...
[19:14:50] Webserver started at http://localhost:4000
[19:14:50] Finished 'dev:serve' after 40 ms
[19:14:50] Finished 'dev' after 1.67 s

Structure

If you run into any issues, check that your project’s file structure matches the recommended suite structure. This is defined to increase consistency and organisation between sites.

.gitignore
Gitignore file.
README.md
This should describe the site and how to manage it.
dist
The output folder for the different states of the sites in the repo.
prod
The output for the gulp dist command.
site
The output for the gulp dev command.
state
The output for the gulp state command.
translated_site
The output for the gulp i18n command.
gulp
The folder for additional gulp scripts.
gulpfile.js
A JavaScript file required to configure CloudCannon suite.
i18n
The folder for the i18n steps.
locales
The folder for the translated locale (.json) files for dist/site. These are used to generate a translated version of the site by running gulp i18n:translate
source.json
The generated locale file from dist/site. To regenerate, run gulp i18n:generate
package-lock.json
A generated file from npm install that prevents unexpected package changes.
package.json
Defines the required installs and repo information. Create this with npm init.
reports
The output location for information gathering commands, like gulp proof
siteicon.png
The icon for the site.
src
The Jekyll source of the site.

App

Resources