Live Editing an Eleventy Project in CloudCannon with Bookshop
November 30, 2023
Watch in 9 minutes
Update December 7, 2023: There is also a blog post for this one, if you prefer reading to watching:
- Learn more about Eleventy and CloudCannon CMS
- CloudCannon Documentation: Introduction to Bookshop with Eleventy
Searchable Transcript
All right, what's up, everybody?Today, I want to talk to you about live editing in CloudCannon.Now, the way that CloudCannon enables liveediting in your project is it uses a plugin called Bookshop.
And to learn about that, we'll go out to the CloudCannon documentation.We'll go to the Guides section.If you scroll down to the bottom,you'll see the two Bookshop guides that CloudCannon provides.
There's one for Astro, and then there's one for Eleventy.And we'll go through the Eleventy one today to build a micro-blog project.And to show you what the final product looks like, here it is.It's just a very simple
micro-blogging project that includes any arbitrary content that you want to putinto it and has a stream of posts, post pages, tags, and tag pages.And inside of the CloudCannon app, you can see the editing experience as well.We have content blocks here.
Now, these are our Bookshop components, and I'll go through those.And importantly, these are live editable.You can reorder them and click through to edit the text.You can click on the text to edit it.
And to get even fancier,we have a link component which shows a screenshot of our external URLthat we're linking out to, and it has it wrapped in a web component as well.So if we link to a different URL,
it automatically updates that and re-renders that web component for us.So let's go through how to wire Bookshop up to our Eleventy project.There is a scaffolding command that we want to run here that will create a newBookshop component library for us in our Eleventy project.
And I've run this scaffolding commandinside of an empty directory to show you what the output looks like.We have our Bookshop configuration file.We have a sample component that was generated for us.
The configuration YAML includes some CloudCannon specific configuration in it.The Blueprint section really determinesdefault placeholder values for our content.The liquid file is the liquid HTML of the output for the component.
And then we have any stylesfor the component we can put in our Sass file as well.We have a page helper that iterates over the components on the pageand re-renders them, and any global styles will go into this global Sass file.
All right, so we've run the scaffolding command.We also want to wire this up to our Eleventy configuration file as well.So Eleventy will render our components as expected.And you can see how to do that down below.
We want to run an `npm install` command.We want to require the Eleventy Bookshop plugin here.And we also want to use Eleventy'sconfiguration API, the addPlugin method, same as you would any other Eleventy plugin
to add this to our Eleventy configuration file as well.Importantly, the Bookshop location here should match `_component-library`the same folder that we specified above in our scaffolding command.And you can see that same code in action on the micro-blog project as well.
And one other thing I like to do is to adda watch target for our underscore component-library folder so that Eleventy willrerun even when we make changes to the liquid template files as well.And the other important thing when we're enabling our local development experience
is that we want to also wire up Bookshop to build our Sass files as well.So you can see that in action here.We have a `bookshop-sass` command,points to the bookshop folder, writes directly to our output folder.
And then we'll watch those Sass files as well to rebuild automatically.And you can see the Eleventy command hereand then the start command, which runs both of these commands in parallel.So that's all we need to enable Bookshop locally.
And this is what it looks like in our local development environment.All right, so now that we got our localdevelopment running, let's go ahead and look at someof the Bookshop components that we're using inside of this project.
You can see that we have a text component here.This is the simplest one.Let's look at our text component.So it's just plain text HTML.
Just put in any arbitrary content here.It's rendered in a liquid templatethat looks like this, not much to it.If you scroll down, you can see we have a couple of code blocks down here as well.
This is a code Bookshop component.It's using Eleventy’s syntax highlighter, and it has three different inputs to it.It has a code block, language, and an extra comment attached to the code.And then maybe the fanciest component here
is that we have a link component, which shows an external URL.We have the URL here.We have the type of preview that we're showing.We can do a screenshot or an OpenGraph image.
We can also have some arbitrary content associated with this one as well.And then we can do light or dark modeon the fake browser window that renders there.I think the next best thing to look at here is a Bookshop template file.
So we have our individual posts inside of our micro-blog.The file name slugs for those are associated with the current date.So if we go out to the *CloudCannon app and go into our Posts section of ourproject, you can see, you can look at existing posts.
And here is the one from November 20th.It's got, again, a link component to text Bookshop components in there.And if you look at the markdownrepresentation of that, you can see those serialized into YAML.
So you can see the text component, text component, link component.Bookshop iterates over these in the content blocks section.And if you remember, if we go back into our Component Libraryfolder in our Shared folder and in Eleventy, you can look at this page.eleventy.liquid
and see this content_blocks data referenced here.We're iterating over the content blocks.We're rendering each as a Bookshop component using the `bookshop` shortcode.And each one of these is rendered live
in the CloudCannon app when the editing is taking place.It's rendering using an Eleventy layout called post.liquidand you can see that in the _includes folder.There's a post.liquid file.
Now, importantly, this is using another Bookshop shortcode called`bookshop_include`, which then is also referencing our Eleventypage helper inside of our component library.So `bookshop_include` here is calling page, which is referencing this other
page.eleventy.liquid file.This is all mapping the components insideof CloudCannon so that we can get that live editing experience.All right, so we have our Bookshop components.
We have our rendered content files,which are using Bookshop Helpers to render those in Eleventy.Before we get the full editing experience in CloudCannon, there's just one moreadditional setup step that we have to do, and that is to add
.cloudcannon postbuild and prebuild commands.Now, these are CloudCannon specific files that run as build hooks for your system.So the prebuild shell script will run before your build runs.And if we look inside of our prebuild,
you can see that we run `npm install` we run `npm run build:style`so if we go back to our package.jsonwe can see `build:style`.This is the same Bookshop command
to bundle our component, Sass files into a single output file.So that's the prebuild file.The postbuild file is a @bookshop/generate *command.Now this wires up additional metadata around your Bookshop components to allow
CloudCannon to hook in for a live editing experience.At some point, this might go away, I don't know.But Bookshop as is today, you do need to run this postbuild script.And all of these development dependencies
are documented on step five of the walk-through.So if you go out and copy this,you'll get the correct dependencies installed and it willdescribe the `@bookshop/generate` postbuild script for you as well.
And there's a lot more to it.Bookshop has a component browser functionality built in.We can go through some of that in later videos,but I think it's important to know that that's basically all you need to do
to get a full live editing experience inside of your Eleventy projectin the CloudCannon app, which I think is great.And as we know, live editing is table stakes for a modern CMS workflow.We really want as much power in the hands of our editors as we can give them,
so that they can feel confident when they're building content inside of the CMSand when they're pushing that content to production.We want those live edits to match the production builds as much as possibleand Bookshop really allows you to do that.