Creating and developing a theme

A theme is a folder of text files (templates, sections, snippets, CSS) that Riseact publishes as immutable versions. Organizations install a version and decide when to update.

You need a Partner account: see the getting started guide.

Installing the CLI

Download the build for your system from the releases page and put the executable on your PATH. Then authenticate:

riseact auth login

Starting from an existing theme

riseact theme init

It clones a starter theme, asks for the manifest.json details (name, identifier, version, author) and creates a folder named after the identifier. The subfolders are described in theme structure.

The identifier is permanent

It ties together the versions of the same theme and cannot be changed. The command warns you if it is already taken.

To start from an already published version:

riseact theme pull -p ./empty-folder

It asks for theme and version and downloads its files.

Developing with the live preview

cd your-theme
riseact theme dev

On the first run it asks which organization to work on and installs the theme there, then prints two addresses: the preview and the visual editor in the panel.

The theme stays in the organization's library without being published: the site donors see does not change. Ctrl+C deletes nothing, and the next theme dev in the same folder picks up from there.

If you have no organization to work on, create a development organization: it is free and has no real data.

The sync goes both ways

While theme dev is running, folder and theme stay aligned:

• a file saved locally is uploaded straight away: just reload the preview;
• a change saved from the visual editor updates the file in the folder.

So colours, texts and page composition are chosen from the editor: compose the homepage by dragging sections and templates/homepage.json updates itself. That file ends up in the release and defines how the theme looks when freshly installed.

On startup the command realigns both sides, so you also get the changes made from the editor while it was stopped.

note

In a conflict the most recent change wins. If the same file changed on both sides while the command was stopped, the server copy wins and the file name is printed.

The session's theme and organization are saved in .riseact/dev.json. Add .riseact/ to your .gitignore; if you delete it, the next theme dev starts from a new theme.

Deleting files

Deletions are propagated only while theme dev is running. A file deleted while the command is stopped is downloaded again from the server on restart.

Excluding files from upload

List build tooling in .riseactignore, at the root of the theme, with the .gitignore syntax:

node_modules
package.json
package-lock.json
yarn.lock
tailwind.config.js
riseact.yml

The rules apply both to the package and to theme dev. .git, node_modules and .riseact are always excluded.

danger

Always include riseact.yml: it holds the CLI credentials and would otherwise be uploaded with the theme.

Compiled output, on the other hand, must be uploaded: with Tailwind, for example, assets/main.css.

Publishing a version

When the theme is ready, raise the version in manifest.json and publish:

riseact theme release

The command opens the editor for the changelog. Organizations read it before updating: write what changes, not how. An empty message cancels the release.

The editor is the first available among $VISUAL, $EDITOR, the editor key in the configuration file, git config core.editor and nano.

Alternatively, riseact theme package prepares a zip to upload from the Partner Area, with the same validation rules.

Versioning rules

The version uses the MAJOR.MINOR.PATCH format (for example 1.4.0), without suffixes such as 1.4.0-beta. The release is refused if:

• the version has already been published for that theme
• the version is lower than the latest published one
• the changelog is empty
• a file does not compile, or a section's {% schema %} block is not valid JSON

If there are file errors, the response lists all of them with their paths and no version is created.

Versions are immutable

A published version is never modified: to fix something you publish a new one.

What the organization sees

In Themes, every installed theme has the Theme version button, from which the organization can:

• pick a version from the list and read its changelog
• see which files it has edited would be overwritten
• update the theme, or install that version as a separate theme

Updates only move forward. An earlier version is installed as a separate theme.

What an update preserves

files	on update
sections/, snippets/, layout/, assets/, config/settings_schema.json, templates/**/*.html	replaced by the new version
config/settings_data.json	kept; new settings are added with their default value
templates/**/*.json	kept; templates new to the version are added

The theme's code is yours, the organization's choices are its own. A change to a section's HTML reaches everybody; a section added to templates/homepage.json reaches only those who install the theme from scratch.

caution

If you rename or remove a section, the templates of the organizations using it show an error in its place. Do not rename sections and do not delete the ones you replace.

Distributing the theme

New versions are available straight away to the organizations that already have the theme. To make it installable by others, from the theme page in the Partner Area choose:

• My organizations: every organization you administer finds it in its theme store, without approval;
• Submit for Approval: it appears in the theme store of every Riseact organization, after our review with a reply by email.

Details in Partner Area: Themes.