Theme development with the CLI

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 click Publish

What you need first

Quick start

# 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

Check you’re on the latest CLI by comparing cobber --version against the version on npm.

Authenticating

cobber login <subdomain>

Replace <subdomain> with the organisation’s subdomain (for example 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.

Working with several organisations. Authenticate with as many as you like — credentials are stored per-subdomain, and the org you logged into most recently becomes the default that cobber pull uses. When you pull a theme the subdomain is saved in the manifest, so cobber dev and cobber push always use the right org for that folder regardless of which is default. Run cobber orgs to see which orgs you’re logged into and which is default (marked with *). Every command prints the org it’s acting on, so you can catch a wrong-org pull before it happens.

Pulling a theme

# 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

What you get on disk

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

Alternate layouts

A template key can carry a suffix. The part before the first dot is the page type; the rest names a variant of it.

page_layouts/home.liquid              # the default home page
page_layouts/home.movement.liquid     # an alternate, selectable per page
page_layouts/collection_item.liquid           # every collection falls back to this
page_layouts/collection_item.candidates.liquid # …unless it has its own

Both files are the same page type, so both are valid; the unsuffixed one stays the default for anything that has not asked for a variant. Create the file, cobber push, and it appears — for a page, in the Layout picker on the page editor; for a collection, automatically, matched on the collection handle.

The suffix has to begin with a real page type. collection_item.candidates is a candidates-specific collection item layout; candidates.liquid on its own is a page type nothing renders.

Collections

A collection is a content type the organisation defines in the dashboard — candidates, policies, media appearances. Each one has a listing page and a page per item, rendered through collection_index and collection_item.

The fields are set up by the customer, so a template addresses them by key:

{%- comment -%} collection_index.candidates.liquid {%- endcomment -%}
{% for item in page.items %}
  <a href="{{ item.url }}">{{ item.title }} — {{ item.electorate }}, {{ item.state }}</a>
{% endfor %}
{% assign pg = page.items.pagination %}

page.items is paginated in exactly the same shape as page.posts, so pager markup ports across unchanged. Any collection is also addressable from any template by its handle, which is what a homepage rail uses:

{% for c in collections.candidates %}{{ c.title }}{% endfor %}
{% collection_items 'candidates', where: 'featured', limit: 4 %}
  {% for item in collection_items %}{{ item.title }}{% endfor %}
{% endcollection_items %}

On an item template the current item is item:

{{ item.title }}  {{ item.url }}  {{ item.headshot }}  {{ item.fields.summary }}

Two field types behave differently from the rest, and they are the reason collections are worth using:

Forms that report back to the CRM

{% widget %} embeds another page’s form. On a collection item, adding attribute_to: tags the submission with that item:

{% widget 'contact' with 'contact_partial', attribute_to: item %}
{% widget 'donate'  with 'donation_partial', attribute_to: item %}

Every enquiry and every donation through that page is then attributed to the item in the CRM, so “everyone who contacted this candidate” is a filter on the People screen rather than a mailbox someone forwards. Nothing else about the widget changes — the hidden field is added for you at render time, so this works with a widget partial you have already customised.

The development loop

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 detects the change, pushes the updated content to the draft, and the preview tab reloads to show it.

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

What the preview shows

The preview renders your draft templates against your organisation’s real content. An events page in preview lists the same events the live site lists, a collection index lists the same items, and a branch page shows the same division details. If a listing looks empty in preview, that is your content — there is nothing published for it yet.

Navigate the preview the way a visitor navigates the site. Every internal link is rewritten to stay inside the preview, so you can reach the page types that aren’t pages in their own right:

Preview also includes unpublished pages, events and items, so you can build a layout before its content goes live.

Checking what data a template was given

Open your browser’s developer console on any preview page. Under Cobber theme preview — page-type data, the preview lists the data it handed the template and what was in it — for example events: 12 upcoming, 3 past. Where something is empty it says so explicitly, so an empty page is never ambiguous between “no content yet” and “this data isn’t available here”. The same list is in the page source as an HTML comment.

When part of the page says “Liquid error: internal”

That is what a tag prints in its own place when it fails — it replaces only that tag, so the rest of the page still renders. The message deliberately says nothing about what went wrong, because it is shown to the public on a live page too.

In a preview, the console tells you the real cause: look for A tag raised while rendering in the same console group, which names the error and the line. If the cause is in your template — a tag given the wrong arguments, say — fix it and save. If it looks like a Cobber problem rather than a template one, send us that console line; it is exactly what we need.

Pushing offline edits

If you used cobber dev, your changes are already on the server: every save was synced live, and you don’t need to push. cobber push is only for files you edited while the dev server wasn’t running.

cobber push

This compares local files against the manifest checksums and uploads any that changed. It also detects new and deleted files. After pushing, the CLI prints a link to the draft review page, which shows a side-by-side diff of every changed template so an admin can see exactly what changed before publishing.

Publishing

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

1. Open the theme

   Go to Settings → Themes in the organisation dashboard, click the theme, then View Draft.

   

2. Review the diff

   Check each changed template side by side.

3. Publish

   Click Publish to make the changes live. The draft is discarded afterwards — run cobber pull again to start a new cycle.

Safe by design. The draft is completely isolated. You can experiment freely — nothing affects the live site until Publish is clicked, and discarding a draft reverts all changes.

Gotchas

The full list of variables, tags and filters available inside a template is in the Liquid reference.