Cobber

Theme Development Guide

Build and customise Cobber themes locally using your favourite code editor. Edit Liquid templates, preview changes live, and publish when you're ready.

Overview

Cobber themes control the look and feel of an organisation's public website. Each theme contains content templates (Liquid HTML files) organised into categories, plus configuration (colours, fonts, custom CSS) managed in the dashboard.

The Cobber CLI lets you pull a theme to disk, edit templates in VS Code or any editor, and sync changes to a draft in real time. The draft is isolated from the live site — nothing goes live until an admin clicks Publish.

How it works

  1. cobber pull — download a draft copy of the theme to your machine
  2. Run cobber dev to start the syncer
  3. Edit .liquid files locally — the CLI syncs each save to the server
  4. Preview your changes instantly in the browser
  5. When you're happy, review the diff in the browser and clicks Publish

Prerequisites

RequirementDetails
Node.jsVersion 20 or later
Dashboard accessAn admin account on the organisation with the websites.develop permission
Code editorAny editor — VS Code, Sublime, Cursor, etc. Install a Liquid syntax extension for highlighting.

Install the CLI

Terminal
npm install -g @cobberhq/cli

This installs the cobber command globally. Verify with cobber --help.

Quick Start

Terminal
# 1. Install
npm install -g @cobberhq/cli

# 2. Authenticate
cobber login patrioticpretzels

# 3. Pull a theme
cobber pull

# 4. Start developing
cd patrioticpretzels-themes/standard
cobber dev

# 5. Edit .liquid files in your editor — changes sync live
# 6. When done, push any offline edits
cobber push

# 7. Review and publish in the dashboard

Authenticate

Terminal
cobber login <subdomain>

Replace <subdomain> with the organisation's subdomain (ie. cobber login patrioticpretzels).

A browser window opens where you log in and approve the device code. The CLI receives a long-lived access token, stored at ~/.cobber/config.json. You only need to do this once per organisation per machine.

Multiple organisations

You can authenticate with as many orgs as you like — just run cobber login for each one. Credentials are stored per-subdomain and the first one you log in to becomes the default. When you cobber pull a theme, the subdomain is saved in the manifest, so cobber dev and cobber push automatically use the right credentials.

Pull a Theme

Terminal
# Interactive — prompts you to pick a theme
cobber pull

# Pull a specific theme by name or slug
cobber pull standard

# Pull every theme at once
cobber pull --all

This creates (or reuses) a draft on the server and downloads all templates to a local directory. The draft is a safe working copy — your changes won't affect the live site.

If a draft already exists for the theme, pull reuses it so you can pick up where you left off.

Directory Structure

After pulling, your project directory looks like this:

File tree
<subdomain>-themes/
  <theme-slug>/
    .cobber/
      manifest.json          # Draft ID, checksums — don't edit
    page_layouts/
      home.liquid             # Homepage template
      donation.liquid          # Donation page template
      membership.liquid        # Membership signup template
      contact.liquid           # Contact page template
      ...
    site_layouts/
      layout.liquid            # Site-wide wrapper (header, footer, nav)
    snippets/
      ...                      # Reusable partial templates
    widget_partials/
      ...                      # Embeddable widget templates
DirectoryPurpose
page_layouts/ One template per page type (home, donation, membership, contact, volunteer, petition, signup, about). Each file controls the HTML for that page type.
site_layouts/ The site-wide layout wrapper. Typically one file (layout.liquid) that includes the <head>, navigation, footer, and a {{ content }} placeholder where page content is injected.
snippets/ Reusable HTML fragments. Include them in other templates with {% snippet "name" %}.
widget_partials/ Templates for embeddable widgets and their success pages.
.cobber/manifest.json Internal metadata — draft ID, file checksums, API endpoint. Don't edit this file.

Each .liquid file maps 1:1 to a ContentTemplate record on the server. The filename (minus the extension) is the template key.

Local Development

Terminal
cd <subdomain>-themes/<theme-slug>
cobber dev

This starts a file watcher and opens a preview URL in your browser. Every time you save a .liquid file, the CLI:

  1. Detects the change
  2. Pushes the updated content to the draft via the API
  3. The preview tab auto-reloads to show your change

The preview URL uses a signed token valid for 24 hours. If it expires, stop and restart cobber dev to get a fresh one.

Tip

Keep the terminal and browser side by side. Edits appear in under a second.

Push & Review

If you used cobber dev, your changes are already on the server — every save was synced live. You don't need to push.

cobber push is only needed if you edited files while the dev server wasn't running (e.g. you made changes offline or on a plane):

Terminal
cobber push

This compares local files against the manifest checksums and uploads any that changed. It also detects new files and deleted files. After pushing, the CLI prints a link to the draft review page in the dashboard.

Draft review

The review page at /dashboard/admin/themes/:id/draft shows a side-by-side diff of every changed template. Admins can inspect exactly what changed before publishing.

Publishing

Publishing merges the draft back into the published theme. This is done by an admin in the dashboard:

  1. Go to Settings → Themes in the organisation dashboard
  2. Click the theme, then View Draft
  3. Review the diff for each changed template
  4. Click Publish to make the changes live

After publishing, the draft is discarded. Run cobber pull again to start a new development cycle.

Safe by design

The draft is completely isolated. You can experiment freely — nothing affects the live site until Publish is clicked. Discarding a draft reverts all changes.

Tips & Gotchas

Colours and fonts live in the dashboard

Theme configuration (primary colour, fonts, custom CSS) is not stored in template files. Edit these in Settings → Themes → Editor. Templates access them via CSS variables.

Don't edit manifest.json

The .cobber/manifest.json file tracks the draft ID and file checksums. Editing it can cause sync issues. If things get out of sync, delete the theme directory and cobber pull again.

Multiple themes

An organisation can have multiple themes. Individual pages can be assigned to different themes, or the entire site can use a single "active" theme. Use cobber pull --all to pull every theme at once.

Liquid Reference →