Creating a theme

Overview

Before you can start developing, you'll need access to a base theme repository and a theme key from Easol.

There are two ways to get started:

Option 1: Start with existing Easol theme

If you're extending or modifying an existing Easol theme, Easol can provide access to fork the relevant theme repository.

Option 2: Start with skeleton theme

If you're building a fully custom experience, Easol can provide access to the skeleton theme repository. The skeleton theme contains the minimum structure, files, and workflows required for an Easol theme.

Reach out to the Easol team here to request access.

Connect your theme to an Easol site

Once you have access to a theme repository:

1. Request your credentials

Contact Easol to obtain:

• A theme key
• An Easol key
• An Easol secret

2. Configure your theme key

In your repository, open:

.github/workflows/main.yml

Update the THEME_KEY value with your assigned theme key.

3. Add your Easol credentials

In GitHub, navigate to:

Settings → Secrets and variables → Actions

Create the following repository secrets:

• EASOL_KEY
• EASOL_SECRET

4. Deploy the theme

After the first successful deployment, any creator with Developer access can install the theme by entering its theme key when selecting a theme for their site.

Develop your theme

When a theme is installed on a site, Easol creates a copy of the theme code for that specific site. Changes made to the source repository are not automatically applied to sites that are already using the theme.

Theme assets must be updated manually

During development and testing, updates to theme assets such as blocks, templates and partials must be uploaded manually through:

Site → Theme

in the Easol company admin.

Existing blocks are not updated

Changes made to a block definition won't update instances of that block that have already been added to pages.

Updated versions will appear in the block library and can be added to pages. To update any existing blocks, you must update the block HTML on the page.

Learn more about blocks.

Monitor deployment status

Whenever you push changes, check the GitHub Actions workflow runs to ensure deployment succeeds.

The key workflows are:

• Canvas Lint
• Theme Deploy

Allow time for changes to propagate

Theme updates can take up to 15 minutes before they become available to sites.