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-rc5"
}

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.

  • share .gitignore

    Gitignore file.

  • code README.md

    This should describe the site and how to manage it.

  • folder dist

    The output folder for the different states of the sites in the repo.

  • folder prod

    The output for the gulp dist command.

  • folder site

    The output for the gulp dev command.

  • folder translated_site

    The output for the gulp i18n command.

  • folder gulp

    The folder for additional gulp scripts.

  • code gulpfile.js

    A JavaScript file required to configure CloudCannon suite.

  • folder i18n

    The folder for the i18n steps.

  • folder 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

  • code source.json

    The generated locale file from dist/site. To regenerate, run gulp i18n:generate

  • code package-lock.json

    A generated file from npm install that prevents unexpected package changes.

  • code package.json

    Defines the required installs and repo information.

  • image siteicon.png

    The icon for the site.

  • folder src

    The Jekyll source of the site.