Raytha themes: files, export, import and the CLI

A theme is the set of templates and media that decides how your site looks. You can edit it in the admin, but a theme also fits in a directory of plain files, which means you can keep it in git, review changes, and deploy with one command. This page covers the theme model, the file layout, the Raytha command line tool, and theme export and import.

What a theme contains

Web templates: layouts, detail and list templates, site page templates, the login and account pages and the error pages.
Widget templates: the blocks editors put on site pages. See Widget templates.
Media: images, stylesheets, scripts and fonts that belong to the theme and have a stable URL.

Exactly one theme is active. The active theme renders the public site, and site pages use its widgets. The built-in raytha_default_theme is a sensible starting point, so copy it instead of starting from an empty directory. Email templates are not part of a theme; see Email templates.

A list view and a content item each point to one template per theme. When you make a theme active, Raytha creates any bindings the new theme is missing: a view or item keeps the template with the same developer name if the new theme has one, and otherwise falls back to the built-in list or detail template. Site pages are not rebound. A page keeps the template it was created with, so check each one after a switch.

In the admin

Open Themes in the admin. From the list you can import a theme with Import from URL. Each theme has its own lists of web templates and widget templates, and a settings page with:

Details: the title and description.
Set as active theme: make this the theme visitors see.
Allow this theme to be exported: see below.
Duplicate theme: copy the templates, widget templates, media and view bindings into a new theme. Use it before a redesign, edit the copy, then activate it.
Delete theme: not available while the theme is active.

Export and import

A theme that allows export is available as JSON at /raytha/themes/export/<developer_name>. The package holds every web template (label, developer name, source, parent, whether it is a base layout), every widget template (including its field definitions) and a list of media files with a download URL for each.

Warning The export address needs no login. Anyone with the URL can download the theme's source whenever Allow this theme to be exported is ticked. Turn it off for themes that contain private markup.

To import, choose Import from URL and enter a title, a developer name, a description and the package URL. The import runs as a background task and creates a new theme. It fails if the developer name is taken. By default Raytha refuses package URLs that point at internal addresses; set ALLOW_INTERNAL_URL_IMPORTS to true if you need to import from one (see Configuration).

The command line tool

The Raytha command line tool talks to a site's API, and it prints JSON, so it works in scripts and in CI. Install it with the release script, then give it your site and an administrator's API key:

curl -fsSL https://github.com/RaythaHQ/raytha-cli/releases/latest/download/install.sh | sh
export RAYTHA_URL=https://your-site.example.com
export RAYTHA_API_KEY=your-key
raytha doctor

The key carries the permissions of the administrator who owns it (see API authentication). raytha doctor checks the address, the key, and which groups of commands it may use.

A theme as a directory

raytha theme pull writes a theme to disk and raytha theme push syncs it back:

my_theme/
  theme.json                         title, developerName, description
  web-templates/
    raytha_html_base_layout.liquid   the template source
    raytha_html_base_layout.json     optional sidecar
    landing.liquid
  widget-templates/
    feature_grid.liquid              the markup
    feature_grid.json                label and fields
  media/
    logo.svg

The file name without its extension is the template's developer name: lowercase letters, digits and underscores.

Web template sidecar

A .json next to a web template sets the things that are not part of the Liquid. Every key is optional:

{
  "label": "Landing page",
  "isBaseLayout": false,
  "parent": "raytha_html_base_layout",
  "allowAccessForNewContentTypes": false,
  "contentTypes": ["posts"]
}

parent names the layout this template inherits from. Do not repeat it in the source. There is no layout tag, and writing one fails at render time. The tool creates parents before children.
isBaseLayout is true for layouts, and a layout must contain {% renderbody %}. See Layouts and inheritance.
contentTypes and allowAccessForNewContentTypes control which content types may use the template. Templates that render content items need them.
Without a sidecar, a new template gets a label made from the file name, and an existing one keeps its remote values.

Widget template sidecar

{
  "label": "Feature grid",
  "fields": [
    { "developerName": "headline", "label": "Headline", "fieldType": "single_line_text" }
  ]
}

The fields are the same JSON as in the admin; see Widget templates.

The workflow

Pull the default theme into a new directory and put it in git: raytha theme pull raytha_default_theme ./site.
Edit theme.json (give the copy its own developer name), the templates and the media.
Preview what would change: raytha theme push ./site --dry-run. Each item is reported as create, update, unchanged, delete, skip or failed. The dry run parses every template, so syntax errors show up here with a line and column.
Push for real: raytha theme push ./site. Add --activate to make the theme live when the push succeeds.
Fetch a page that uses what you changed and read the HTML. Runtime errors only appear when a page renders.

raytha theme pull raytha_default_theme ./site
raytha theme push ./site --dry-run
raytha theme push ./site
raytha theme push ./site --activate
raytha web-template validate --file ./site/web-templates/landing.liquid
raytha web-template preview my_theme landing --out /tmp/landing.html
raytha check

Push is repeatable: it compares each body and only changes what differs, so running it twice changes nothing the second time. If some items fail, the command exits non-zero with the code push_incomplete and a report. Fix those files and push again; the items that went through are not repeated.

Flag	Effect
`--dry-run`	Report only. Nothing is written.
`--activate`	Activate the theme after a successful push.
`--prune`	Delete remote templates and media that are not in the directory. Built-in templates are never deleted. Always combine it with `--dry-run` first.
`--theme other_name`	Push the directory into a different theme, for staging.
`--no-media`, `--replace-media`	Skip media, or re-upload files whose size differs. By default new files upload and existing names are left alone.

Moving a live site to a new design

raytha theme duplicate my_theme my_theme_v2 --wait
raytha theme pull my_theme_v2 ./site_v2
raytha theme push ./site_v2 --dry-run
raytha theme usage my_theme_v2 --unused
raytha theme activate my_theme_v2

Duplicating keeps every view and item binding, so you do not have to re-link anything. theme usage lists, for each template, the views, items, site pages and child templates that use it. Check it before you delete or rename a template. Raytha refuses to delete a web template that a site page uses.

Gotchas

pull overwrites local files. Pull into a fresh directory, or commit first.
Every theme needs Raytha's built-in templates (login pages, error pages, the list and detail fallbacks and the page layouts). Creating a theme adds them. Override them rather than deleting them.
Editing a web template replaces its list of allowed content types. Push keeps the current list unless the sidecar gives one.
A theme created from scratch has no bindings for existing views and items. Prefer theme duplicate. If you start from a fresh theme, activating it creates the missing bindings, using the built-in list and detail templates where the old template name does not exist.

Themes and the command line tool