Eleventy plugin Kirby CMS

This is a plugin for the static-site generator Eleventy (11ty) that helps to build decoupled front-ends based on content from Kirby CMS. It offers functions to retrieve content from Kirby via it's API, generate pages from that data and adds filters to work with the content.

Important note: While in it's current form it's already functional and can be used in projects, this is in an early try-and-error phase, gradually changed and improved for the best workflow, and thus is indented to change, including breaking changes. If you're willing to use it in it's current form, be prepared for bigger changes. This is currently successfully used in at least 3 projects.

The manual in the README might not be complete yet.

• Eleventy plugin Kirby CMS
  • Requirements
  • Setup
    • Plugin
      • Installation
      • Configuration
    • Kirby CMS API user
  • Usage
    • Generate all pages
  • Reference
  • Development
    • Development environment
      • One-time setup
      • Usage
    • Requirements to run locally without Docker

Requirements

1. Node.js v14.x.x*
2. @11ty/eleventy
3. A Kirby CMS installation
4. Kirby KQL Plugin installed

*Might work with older Node.js versions too, without a garantuee

Setup

Plugin

Installation

Then install the plugin via npm:

$ npm install eleventy-plugin-kirby

Optionally, add .eleventy-plugin-kirby to your .gitignore. This is a temporary folder storing debug logs when activated with the debug option.

Configuration

Add the plugin to your .eleventy.js configuration. You need a user in your Kirby CMS instance (see Kirby CMS API user) for read access on the API.

Currently, the configuration can only be done via Node.js environment variables.

Recommended way with dotenv

require("dotenv").config();
const eleventyPluginKirby = require("eleventy-plugin-kirby");

module.exports = function (eleventyConfig) {
    eleventyConfig.addPlugin(eleventyPluginKirby);
};

Required environment variables:

# URL to the Kirby CMS installation
API_KIRBYCMS_URL="https://example.com"

# API user
API_KIRBYCMS_USER="user@example.com"

# API user password
API_KIRBYCMS_PASSWORD="password"

Refer to the dotenv documentation for proper setup with the .env file.

Using dotenv is completely optional to pass the configuration to the environment variables.

Kirby CMS API user

To retrieve data from the CMS, you need a user with read access to all data including the panel.

1. Create user permission blueprint: You'll find a prepared user blueprint for the permissions of such a user in src/blueprints/users/api.yml of this plugins repository, to be placed in site/blueprints/users of your Kirby CMS installation.
2. Create a user in your CMS with the given permissions.
3. Pass user and password via environment variables to the Eleventy plugin, see Configuration.

Usage

See documentation for all filters and query functions that are available. In the following section, we highlight some useful features to make it easier getting started with the plugin.

Generate all pages

The intendet way to use this plugin is to let it generate all public pages for the front-end instead of querying every page individually. In this example we use Liquid as templating engine, but it should work with most other templating engines supported by Eleventy which work with the pagination option.

1. Create _data/kirby.js
   Create a data file to retrieve all pages from Kirby. You can name it whatever you want. In this example we use kirby.js and will later refer to this as kirby.

   const { getAll } = require("eleventy-plugin-kirby");
   
   module.exports = async function () {
       const data = await getAll();
   
       return data;
   };

2. Create pages.liquid
   This is the template generating all the pages. We alias the individual page's data to data for easier access.

   ---
   pagination:
       data: kirby.entities.pages
       size: 1
       alias: data
       resolve: values
       addAllPagesToCollections: true
   permalink: "{{ data._permalink }}/index.html"
   tags: "data"
   ---
   <h1>{{data.title}}</h1>

Reference

See documentation.

Development

This part is for people who want to contribute to the plugin

Development environment

The default development environment is Docker with Docker Compose. Even though to go up and running withdocker-copose up don't want to use Docker, make sure thedemo/kirbycmsis served by an Apache server locally anddemo/11ty-web-frontend` can reach it's address.project. it's not necessary to use Docker to run the project locally, I recommend it because it comes with two services, one for for the demo front-end and one for the dem Kirby CMS.

One-time setup

1. Duplicate demo/kirbycms/.env.example to .env.

2. Start the Kirby CMS

   $ docker-compose up kirbycms

3. Navigate to localhost:3002/panel and setup your personal, local admin CMS user.

4. Go to user accounts and add a new user named "api@example.com" with the user permissions "API".

5. Duplicate demo/11ty-web-frontend/.env.example as .env and fill in the

6. credentials of previously created API user.

7. Stop the Docker environment

   $ docker-compose down

Usage

$ docker-compose up

This starts two services: The 11ty-web-frontend (localhost:3000) and the kirbycms (localhost:3002/panel). You're now ready to make changes to the plugin.

Requirements to run locally without Docker

If you don't want to use Docker, make sure the demo/kirbycms is served by an Apache server locally and demo/11ty-web-frontend can reach it's address.

• demo/kirbycms needs to be run with an Apache PHP server, e.g. Mamp.
• demo/11ty-web-frontend needs to be run with the predefined Node.js version, see .nvmrc.
• Path to Kirby CMS has to be correctly changed in .env of both, the demo/11ty-web-frontend and the demo/kirbycms folders.