Component templating

Bookshop components use the templating language of your chosen static site generator. For Eleventy, Bookshop supports writing components as .liquid files.

Creating your first component#

If you followed the previous Getting set up section of this guide and ran the @bookshop/init command, a sample component will have been created for you:

_component-library/
└─ components/
   └─ sample/
      ├─ sample.bookshop.yml
      ├─ sample.scss
      └─ sample.eleventy.liquid

Bookshop components live in the components/ directory, each inside a folder matching their name.

For now, we're going to ignore the .scss and .bookshop.yml files and just look at the .eleventy.liquid templating file. If you don't have this component, create an empty file at components/sample/sample.eleventy.liquid in your Bookshop folder.

If we look inside the sample file that was created for us, we'll see:

<div class="c-sample">
  <p>{{ text }}</p>
</div>

If you're used to writing Liquid includes on your Eleventy site, the contents of this component should be very familiar. Beyond the special directory structure that this component should live in, the templating can (in most cases) be migrated directly from any existing Eleventy includes.

Here's a hypothetical component that uses more Liquid syntax:

<div class="c-hero">
  <p class="date">Published on {{ publish_date | date: '%a, %b %d, %y' }}</p>
  <h1>{{ title }}</h1>
  {% if subtitle %}
    <h2>{{ subtitle }}</h2>
  {% endif %}
</div>

Scaffolding new components#

The @bookshop/init command also provides a way to create new components:

npx @bookshop/init --component <name>

Running the above command in an existing Bookshop will scaffold out some initial component files for you.

Supported templating filters and functions#

There are some restrictions on the features you can use inside your components. Since Bookshop renders your components in the browser, any custom filters you define in your .eleventy.js configuration won't be available.

Any filters that are defined in the LiquidJS Filter documentation will be available, and Bookshop also provides working markdownify, slugify, and url filters that match Eleventy's default logic.

Bookshop only has access to the files in your component browser when live editing, so accessing any of your Eleventy includes from within a component will cause an error in the Visual Editor. If these need to be accessed, turn them into Bookshop components, or use Bookshop's bookshop_include feature.