Bookshop — our open-source page-building toolkit — now supports Hugo, as well as Jekyll and Eleventy.
If you missed our Bookshop launch post in October last year, here’s a quick recap: Bookshop empowers you to integrate components with your stack, build and browse UI components locally, and provide rich visual page-building experiences for your editors. Bookshop integrates tightly with CloudCannon for your content management needs. Editors can see the entire catalog of components available and use them to build pages visually, all powered by your custom-built component library.
Feature development has continued in the months since release, adding automatic Visual Data Bindings, Eleventy 1.0 support, and now a rich Hugo integration.
Before we discuss Hugo and Bookshop, we should get a foundational understanding of what it means to preview changes live on CloudCannon, and why Bookshop exists to help integrate it into your stack.
Next up in the page-builder feature set is Visual Data Bindings. These bindings tell CloudCannon to associate a region of your page with a block of data from the front-matter. With this in place, CloudCannon can provide popouts in the Visual Editor, allowing you to add components and edit data contextually without having to hunt through the sidebar for an object (inside an object (inside an array)) ad infinitum.
The last pillar of the page-building experience is Structures. To build a meaningful page out of data, you need some structure to that data (read: components) so that editors can add and remove items to the page. Structures let you define a list of objects that you can add, remove, or rearrange in particular locations.
Using these ingredients, you can build a fully featured page builder within CloudCannon. Your editor can click a Visual Data Binding to open a panel, within which they add a new Structure to a components array, at which point your page uses the Live Editing API to catch that change and update the page.
Building this system into a site is extremely powerful, but it can also be a lot of work to get it up and running. This is where we finally reach Bookshop, and why we build and maintain it.
Now that we know the game we’re playing, how does Bookshop fit into the picture?
Bookshop requires some conventions in the way you build your site. Components live in a specific structure within the Bookshop directory, and a schema file lives alongside each component. Outside these tweaks to your workflow, Bookshop gets out of the way — within your layouts, you use the Bookshop tags like you would an include or a partial.
On its own, that isn’t ground-breaking, but because of the conventions under the hood, Bookshop can put an entire page builder together for you:
A component begins its life in the Bookshop components directory. For Hugo, we write a hero component at
components/hero/hero.hugo.html. This file is identical to a Hugo partial you might write elsewhere, and you have most Hugo functionality within it.
hugo.html file, we then write a matching
hero.bookshop.toml file — this is the component config. It might look like the following:
[props] we define the fields that this component takes, with some example data that we can see in the component browser. You can think of this as the component schema; Bookshop uses
[props] to create Structures in CloudCannon. Special keywords in this file exist as shortcuts to common CloudCannon features. In this case,
style.select will configure a CloudCannon Select input for the
style key, with
Compact as options.
[component] section tells Bookshop where to put the Structures. The important part here is the
structures keyword, which in the above example means: “an editor can add the hero component to any array in the front-matter named
In CloudCannon, the editor would see the following:
Component config files tagged with the correct structure will automatically populate these modals.
Let’s take a peek at the generated front-matter when a user adds a new
This object should look familiar. The component config we wrote earlier created the fields we now see, and the
style keyword now shows the selected option. Additionally, we see a
_bookshop_name field generated by Bookshop that identifies this component.
To get this onto the page in Hugo, an object with a
_bookshop_name key can be passed to the
bookshop partial directly:
Tip: Only files from your Bookshop will update live in the visual editor, so putting the above loop within a Bookshop component will ensure that adding or removing Structures to the
content_blocks array will update the page correctly. See how the starter template implements this for an example.
With those steps, we have created the essential parts of our page builder. There are some one-off pieces of configuration to set up before you’ll see updates live, so make sure to read through the Hugo Bookshop Guide while setting this up on a site. Once that’s all done, your editors will be able to add, edit, remove, and rearrange components on the page — all without any developer input.
Whether you run an agency with new projects rolling in, or a business maintaining a fleet of microsites, Bookshop allows you to empower your editors with a rich, custom-built component library — while you get to work on the next big thing. With the Hugo module system, you can even bring new components to old sites and enhance their editing experience over time.
We first brought this workflow to the Jekyll and Eleventy communities in Bookshop 2.0, and we have seen many stunning examples of rich contextual editing that our customers have built on this stack. I’m personally very excited to now have this workflow available in Hugo.
The best way to get started is to read the Hugo Bookshop Guide and check out the Bookshop Hugo Starter template. These resources explain how a Bookshop project in Hugo plugs together, and the starter template provides an example of a simple page builder functioning in the CloudCannon Visual Editor. If you get stuck and need a hand, pop over to the Bookshop issues on GitHub or get in touch with our support team in-app.
21 January 2023
14 January 2023
4 January 2023