Configuring your build

Last modified: November 8th, 2023

Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.

Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.

Sites can be configured to build using Jekyll, Hugo, Eleventy, Next.js, Nuxt, Gatsby, SvelteKit, Astro, MkDocs, Static, or Custom.

When connecting your site, you will be asked to select your SSG to build with. You can change this at any time by:

  1. Navigating to your site's settings
  2. Navigating to Builds / Build
  3. Selecting your SSG from the dropdown, then clicking Update Configuration at the bottom of the page

Build Step#

Here you can find what commands CloudCannon uses to build your sites. Learn more about extending your build process with hooks.

specific doc

Jekyll is one of the first popular SSGs. Learn how you can customize Jekyll and the build environment to your needs.

Sites without a Gemfile are built with:

shell
copied
jekyll build

Sites with a Gemfile are built with:

shell
copied
bundle install
bundle exec jekyll build

These commands are run in the root folder of your site.

If your Gemfile isn’t in the root folder, set the BUNDLE_GEMFILE environment variable to tell the Bundler where to find it. Setting this requires that your gems are specified in the _config.yml file.

specific doc

Hugo is a popular SSG built using Golang.

Hugo sites are built with:

shell
copied
hugo

specific doc

Eleventy (or 11ty) is a popular static site generator built with Node.js.

Eleventy sites are built with:

shell
copied
npx @11ty/eleventy

specific doc

Static is the most basic SSG option available on CloudCannon.

Files are copied to the live site as-is. CloudCannon performs optimizations and processes static-specific hosting features on the files.

specific doc

CloudCannon provides a build command for each known SSG, and this can be changed to suit your build. The build command is set in the build configuration when you select an SSG.

Setting your SSG version#

It's good practice to specify which version of your static site generator you use to avoid errors and unexpected behavior. CloudCannon offers different methods to manage this based on which generator you use.

specific doc

CloudCannon supports Jekyll versions after 2.4.0. New sites without the version set use a default version. The version is displayed in the Status section after each build.

Set the version to avoid future breaking changes and version clashes across environments.

To set the version:

  1. Add a Gemfile to the root folder
  2. Add the jekyll dependency to your Gemfile
  3. Set the version as required
Gemfile
copied
source "https://rubygems.org"
gem "jekyll", "~> 4.1.1"

By default, CloudCannon uses /Gemfile as the gem source. To change this you can set the BUNDLE_GEMFILE environment variable (e.g. BUNDLE_GEMFILE=src/Gemfile).

Setting the BUNDLE_GEMFILE environment variable requires that your gems are specified in the _config.yml file.

specific doc

By default CloudCannon builds using Hugo version 0.122.0. You can change which version of Hugo your build uses by running the install-hugo command in a preinstall hook.

For example, to build your site using an older version of Hugo:

.cloudcannon/preinstall
copied
install-hugo 0.100.2

Do not include _extended or +extended in your version. CloudCannon will automatically use the extended release of the specified version.

specific doc

CloudCannon builds with any version of Eleventy, although is focused from version v0.12.1 onward.

Since we build Eleventy sites with npx, the latest version is run unless specified otherwise in package.json.

specific doc

CloudCannon uses the version you specify for your SSG with npm or another package manager.

Changing your CLI options#

Most static site generators offer a number of configuration options for use on the command line. Configure these and other CloudCannon-specific build options per site.

To change a command line build option:

  1. Go to the Site Settings / Build section
  2. Change details for one or more options
  3. Click Update Configuration

See in-depth details for configuring Environments and Optimizations

Build Configuration interface

Using Environment Variables#

Environments allow you to use different values in your website depending on where it is deployed. For example, you could use a different CDN for your development, staging and production sites.

To change the environment variables for your site:

  1. Go to the Site Settings / Configuration section
  2. Create/edit your environment key and value under Environment Variables
  3. Click Update Build Details

specific doc

CloudCannon defaults to production. Running Jekyll locally defaults to development.

shell
copied
$ JEKYLL_ENV=production bundle exec jekyll serve

Jekyll exposes the environment with jekyll.environment. You can use this to create separate configurations.

Here’s a short example using variables from _config.yml:

_config.yml
copied
development:
  asset_url: "http://localhost:1337/"
  app_url: "http://localhost:3000/"

staging:
  asset_url: "https://staging.example.org/assets/"
  app_url: "https://staging.example.org/"

production:
  asset_url: "https://cdn.example.org/"
  app_url: "https://app.example.org/"
index.html
copied
---
---

<p>Environment: {{ jekyll.environment }}</p>
<p>Asset URL: {{ site[jekyll.environment].asset_url }}</p>
<p>App URL: {{ site[jekyll.environment].app_url }}</p>
<p>Development Asset URL: {{ site.development.asset_url }}</p>
<p>Production Asset URL: {{ site.production.asset_url }}</p>
<p>Staging Asset URL: {{ site.staging.asset_url }}</p>
<p>Development App URL: {{ site.development.app_url }}</p>
<p>Staging App URL: {{ site.staging.app_url }}</p>
<p>Production App URL: {{ site.production.app_url }}</p>

specific doc

CloudCannon defaults to production. Running hugo locally defaults to production. Running hugo server locally defaults to development.

To change the environment locally, set it before running Hugo:

shell
copied
$ HUGO_ENV=production hugo

You can set the Hugo environment using the —-environment flag in the command line. Learn more about build configuration.

Hugo exposes the environment with hugo.Environment.

Using a configuration directory allows you to create separate configurations for each environment. See the example in the Hugo documentation.

specific doc

CloudCannon has no default. You should set your environment variables everywhere you need them before building. The Eleventy documentation mentions ELEVENTY_ENV as a convention.

To change the environment locally, set it before running Eleventy:

shell
copied
$ ELEVENTY_ENV=production npx @11ty/eleventy

specific doc

CloudCannon does not set default environment variables for custom SSGs.

To change an environment variable locally, set it before running your build command:

shell
copied
  $ MY_ENV_VAR=hello <build command>

Related Articles

Open in a new tab