Choose your preferred SSG:
Choose your preferred SSG:

Hugo Starter Guide

This guide will walk you through the steps required to get your Hugo site built, editable and live on CloudCannon.

Hugo is lightning fast, powered by golang, and is one of the most popular and dependable SSGs available. CloudCannon makes it easy to store your content in your Git Repository and have non-developers update it. There’s no need to teach people about front matter, markdown or Git.

1: Sync your files

The first step for connecting any site is to get your file system linked to CloudCannon. CloudCannon will need to clone your files to disk before anything else — this is the same process as if you were working locally in your development environment.

CloudCannon offers multiple ways of connecting your files:

  1. Git syncing through GitHub, Bitbucket, GitLab and self-hosted GitLab
  2. Uploading a folder or zip of your files

It is highly recommended that you use the Git syncing option. This allows your updates on CloudCannon to push back to your repository. Your editors can then contribute to the Software Development Life Cycle (SDLC). This step is configured through an OAuth connection with the relevant partner. Check out the Connecting Your First Site guide for more information on this step.

2: Build your site

The second step for any new site is to get a successful build. This also mirrors your local development environment. On CloudCannon, select Hugo as your SSG — this may already be set if we can detect a Hugo looking folder structure.

CloudCannon waiting for Hugo build options

The important things to configure here are:

  • Any required environment variables
  • Any non-default CLI options. Hugo has an enormous list of these, all of which are configurable in CloudCannon. Most of these can be ignored right now, but here are a few that might be useful:
    • Source -s, –source: The folder that your content is in. This will default to your root directory. Some people add a source folder if the repo is shared with other projects
    • Destination -d, –destination: Path to write files to. The default value public is usually fine. If you output to a different folder locally, it is nice to match it on CloudCannon so that any scripts reading from the output can work the same way.
    • Base URL -b, –baseURL: Hostname and path to the root (e.g. https://example.com/). This is useful if you are using subpaths in CloudCannon. You can build multiple sites onto the same domain.
Hugos many CLI options customisable in CloudCannon

Ideally your build will work the first time. If this is the case, you can move to the next step. If your build did not work the first time, be sure to read the build output — this will let you know what didn’t work.

You may find you need extra commands to complete your build. A common example is using postcss; for this you can use build hooks, adding specially named bash scripts that run at different steps in the build. For more information, see the build hook documentation.

Interlude: Your site is built

Once your site is built, you will see a big green tick on the screen. At this point, your site’s files are synced and a successful build has been run. This means you have unlocked a newly generated preview URL. In the top left corner of the screen under your site name, there is a blue link, styled adjective-noun.cloudvent.net. Clicking this link will open a new tab to the hosted site on CloudCannon. It is a helpful step at this point to check that the site looks correct. If it does, you can move on to editor configuration. If you need to update your build, this can be done in your settings.

Note

Your new adjective-noun.cloudvent.net site will give you a preview after every change. Use this to show off your new site.

Interlude: Editing terminology

Hugo and CloudCannon are like long-time best friends. Hugo has its collections and data organized in a strong and rigid pattern. CloudCannon knows Hugo so well that editing of these are automatic straight away.

CloudCannon has a few concepts that line up with Hugo concepts:

  • Data: These are standalone data files. This is ideal for site configuration or files that don’t need to repeat. Data is edited by altering to a single file.
  • Collections: A folder of files that represent a repeatable data format. This is a good fit for pages, blogs, staff members, recipes, etc. Collections are edited by altering any file or adding more files.

CloudCannon supports a set of file formats for files in Data or Collections:

  • Structured data files: JSON, YAML, TOML, CSV, TSV
  • Markup files: HTML, Markdown
  • Combination files: HTML with front matter, Markdown with front matter

3: Configuring CloudCannon

With your collections all in CloudCannon already, we can focus on polishing the experience for your editors. A good place to start is expanding on your collection configuration. This allows you to add things like:

  1. Icons, names, descriptions, and documentation links to the collection interface
  2. Define which editors can be used to edit each collection item
  3. The order of the sidebar and titles in which collections are groups (e.g. Blogging > Posts)
  4. Show and hide collections

The global configuration file is one of many places that configuration can exist. Some options can exist only in the global config. Others options can be configured in a number of places; these options always start with an _ character. These options cascade like CSS: the more specific the options are, the more they take precedence. From least important to most important, the order is:

  1. Global configuration
  2. Collection configuration
  3. Front matter
  4. Containing structure

4: Configuring inputs

A common option to be configured in the cascade is _inputs. This option allows you to change what input is used for which keys. This can be anything from a text input, color pickers, select fields, date pickers and more. By default, CloudCannon uses the format of your data and keys to decide on the input to use. It is best to review each collection and adjust these as needed.

Another great cascade option is _structureswhich allows you to control how new array and object items are added. Arrays are a great way to create page builders or a configurable navigation. The next section will discuss a system for generating structures automatically.

5: Implement visual editing

Visual editing on CloudCannon can be broken down into two separate parts:

  1. Previews: When data is changed in a data editor, the new changes are visible immediately on the page.
  2. Bindings: Tagging elements on the page tells CloudCannon where the data came from. CloudCannon can then attach a UI to those parts directly on the page. This frees the editor from using the Data Editor in the sidebar.

The final result is something intuitive and easy to teach.

CloudCannons live editing a Hugo site with data panel

Hugo is a Go-based static site generator which means that all the work of building the page happens on a server. To solve this issue we have created a system for organizing and building components called Bookshop. Bookshop uses a stripped-down version of Hugo that can run in the browser, which means there is no new templating language to learn.

CloudCannon works with Hugo like it does with Bookshop — simply and intuitively. You will be able to build pages out of components and see these changes instantly on the page.

6: Rejoice & Share

That’s it for Hugo! Once you have worked through all of this, you will be an expert at creating and configuring CloudCannon sites. Be sure to share your new site with your team or clients.

If you have an internal team, see team sharing. If you have a client, see client sharing. If you need more information, check out our SSO/SAML support.

If you experience any issues with your Hugo build, don’t hesitate to contact our support team.

Was this article helpful? or Suggest an improvement >

Other Resources

  1. Setting up Bookshop on Hugo