Let’s create a microblog with visual editing using Bookshop and Eleventy

Visual editing is table stakes for a modern content management workflow. Using CloudCannon, it’s straightforward to add visual editing to your project using the same workflow your development team already loves.

Visual editing empowers editors to feel confident when building content inside of the CMS and having that content look identical when it is pushed to production.

To get visual editing up and running with CloudCannon, we’ll use a plugin called Bookshop. In the guides section of the CloudCannon documentation you can find a section dedicated to Bookshop, with guides specifically for Astro and Eleventy.

Let’s make a Microblog

In this post we’re going to go through the minimum viable steps to add Bookshop Visual Editing to an Eleventy Microblog (think something akin to Tumblr).

You can head over to GitHub to read through the final source code of the Microblog project. Feel free to fork the repository and deploy your own version to CloudCannon to try this out for yourself!

A live demo of the final product is also available (with a few sample posts). Editors can add any arbitrary HTML content to the blog and the project includes pages for the content stream, individual posts, tags, and also on-page search (via Pagefind).

Set up Bookshop

Scaffolding

To create the initial Bookshop component files and folder structure, you can run the following command to populate the _component-library folder:

npx @bookshop/init --new _component-library --framework eleventy

Installation

Next, let’s install our Bookshop dependencies. You can install everything you need for Bookshop with this command:

npm install --save-dev --save-exact @bookshop/eleventy-bookshop @bookshop/sass @bookshop/generate @bookshop/eleventy-engine npm-run-all

• @bookshop/eleventy-bookshop to add Bookshop shortcodes to Eleventy.

• @bookshop/sass to compile our Sass stylesheets.

• @bookshop/generate @bookshop/eleventy-engine to enable Live Editing features on CloudCannon (these are not necessary for local development)

• npm-run-all: (not Bookshop-specific) used during local development to run Eleventy and our Sass compiler side-by-side

Eleventy Configuration

Next we’ll want to add Bookshop’s Eleventy plugin to our Eleventy configuration file (likely .eleventy.js or eleventy.config.js) the same as you would any other Eleventy plugin.

const pluginBookshop = require("@bookshop/eleventy-bookshop");

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(pluginBookshop({
    bookshopLocations: ["_component-library"]
  }));
};

The bookshopLocations configuration property must match the folder name specified in our scaffolding command (npx @bookshop/init …) above.

Compiling Sass

We’ll also need to compile our Bookshop component styles, which you can do with the bookshop-sass command in these handy npm script additions to your package.json:

{
  "scripts": {
    "build:style": "bookshop-sass --bookshop _component-library --output _site/public/bookshop.css",
    "dev:style": "npm run build:style -- --watch",
    "dev:content": "npx @11ty/eleventy --serve --quiet",
    "start": "run-p dev:*"
  }
}

Now we simply run npm start to start Eleventy’s local development server and Bookshop is running locally!

CloudCannon Build Hooks

Finally, we’ll add two CloudCannon build hooks to run our Bookshop integrations on the CloudCannon servers. We will create two files: .cloudcannon/prebuild and .cloudcannon/postbuild.

.cloudcannon/prebuild:

#!/usr/bin/env bash

npm install
npm run build:style

.cloudcannon/postbuild:

#!/usr/bin/env bash

npx @bookshop/generate

Using Bookshop

Now that our setup is complete we can move on to the fun part: creating Bookshop components. At time of writing, our Microblog project has three Bookshop components: text, code, and link.

You can view the source code for our finished Microblog components for code, link, and text.

The simplest of these is the text component which holds on to no more than plain ol’ HTML content. Each Bookshop component can be represented in three files and text is no exception:

• text.bookshop.yml for CloudCannon specific configuration (including input types).

• text.eleventy.liquid for Liquid templating syntax for the component.

• text.scss for component styles.

When we make changes to the HTML content in a text component in the CloudCannon interface, the visual rendering of the component will be updated in real time in the visual editor.

If you’d like to see a preview of how the visual editing experience looks and behaves, skip to 0:46 in this video on YouTube (or watch below).

You can mix and combine these Bookshop components together to create a post on the blog and the values for each of the component instances are serialized as content_blocks in the template’s front matter (view a sample post).

Works With Web Components

Perhaps more interestingly, the link Bookshop component uses the <browser-window> web component and is editable without any configuration or introspection into the web component’s code — and this example demonstrates re-rendering compatibility with Shadow DOM web components too.

Any changes to the link URL are automatically reflected in the web component and the screenshot with favicon are updated accordingly.

Current Limitations

Shortcodes are not supported in Bookshop components. Guarding the shortcode with env_bookshop_live is not yet a viable workaround. This is a Liquid limitation with parsing unknown shortcode names that we hope to fix soon. Try to switch your shortcode to use a filter instead and it will work fine.

That’s it!

We now have a visual editing interface for our Microblog. Editors can now add or edit entries easily and predictably — but there is more! On the full Bookshop guide you can learn more about data binding, live editing fallbacks, custom plugins, preview thumbnails, and the component playground (everybody loves a style guide!).

Poster image photo by Ivo Rainha.