Creek Theme Toolkit
A theme developer toolkit for the Creek website platform and its Themes API.
On npm: thm
-
Develop themes with your favorite text editor.
- Just edit the files. Then, push your changes to the remote website to preview them. Or, use the automatic file watcher.
-
Edit staging themes, and push changes live when ready.
-
Use:
thm status publish
-
Or, if using git,
git merge
your development branch with your public branch, andthm sync up
.
-
-
Safely collaborate with git.
- When you create a git branch,
thm
will create a remote theme for that branch. Merge and sync when ready.
- When you create a git branch,
-
Download and use themes.
- Get packaged themes, and install them on your website, all from the CLI.
-
Manage your API keys for theme design.
- Easily maintain the designs for multiple Creek-powered websites.
Quick start
-
Install from npm:
npm install -g thm
-
Install settings:
thm install
-
Get list of available themes:
thm list example-domain.com
-
Get a theme:
- If no git repo:
thm download 123@example-domain.com
(replace theme ID "123" and domain) - If git repo:
git clone git@labs.creek.fm:stations/theme-name
- If no git repo:
-
Start inside the theme directory:
cd 123
-
Start file watcher:
thm watch
-
Edit stuff. It will automatically upload.
-
Preview at: example-domain.com
- If you don't see changes, do
thm status edit
to set this as the "preview" theme. - You must also be logged into the website under your account.
- If you don't see changes, do
Getting started
Like the quick start guide, but longer.
1. Install
- Make sure that you have Node.js installed on your system.
- Install the toolkit with npm:
npm install -g thm
- Install your user settings:
thm install
- Follow the instructions to install your API key and website domain.
- You can get your API key here:
- Sign into the Control Panel.
- Click your name in the top right corner.
- Profile.
- Look for API key (you may need to reset it before it works).
2. Get themes
-
cd
into wherever you want to edit a theme. - List the available themes:
thm list example-domain.com
- Download a theme to your local machine:
thm download 123@example-domain.com
- In this example, 123 is the ID number of the theme.
3. Edit themes
-
cd
into the theme's directory. - Make it your remote editing/preview theme:
thm status edit
- Now you can see this theme in your browser, when you view the remote website (example-domain.com).
- Edit the theme files.
- Use any text editor to edit files in ./blocks, ./templates, ./pages, or ./files.
- Or, if you add any images or other other binary files to
./files
they will also be uploaded.
- Push the changes to the remote website:
- For individual files:
thm push /full/path/to/file
- Automatically watch files:
thm push /full/path/to/file
- Upload all files:
thm sync up
- For individual files:
4. Publish a theme
- First, make sure you are previewing the development/staging theme. Use
thm status edit
to check it out. - If everything looks good, then publish the theme to the live website:
thm status publish
Using git
You can use git to collaborate on multiple theme branches.
The theme editor's git integration will create a new version of the theme at the remote website for each branch, allowing you to preview your branch, and not have your code edits collide with other collaborators.
Set up git
- Download a theme:
thm download 123@example-website.com
-
cd 123
- Replace
123
with the theme name or ID.
- Replace
- Run
git init
to turn this theme into a git repo. - Add files, add origin, commit, and push to your remote repo.
- You can find instructions at your git host of choice: GitHub, BitBucket, GitLab, etc.
Basic theme branch workflow
Use the git branch workflow to safely edit multiple versions of your website's theme, and publish when ready.
-
cd
into the theme directory. - Create a new branch, or edit an exiting one.
-
Create new branch:
-
git checkout -b name-of-new-branch
to create a new branch. -
thm sync up
— sync up to create a new theme for this branch at the remote website:
-
-
Edit existing branch:
-
git checkout name-of-existing-branch
-
-
Create new branch:
- Set this branch as the remote editing theme:
thm status edit
- This will allow you to preview it on the actual website:
example-website.org
- This will allow you to preview it on the actual website:
- Work on the theme as usual.
- Edit the theme files.
- Use any git commands.
- When ready, publish the new version.
- Merge the development branch into the public branch.
- For example, merge
edit-the-thing
withmaster
. - Or, you can just publish the new branch:
thm status publish
- For example, merge
-
thm sync up
to sync the changes to the remote website and publish them.
- Merge the development branch into the public branch.
Tips
- Creek will add a "branch" label in the theme editor.
- Add
git_url: "http://github.com/example/example-repo
to your theme.json to keep track of this theme's official repository, so that collaborators know where to go.
Commands
Use theme tools with these commands.
From a theme directory
Run these after cd
-ing into the theme's directory.
thm watch
- Automatically watch for file changes and pushes them to the remote website.
thm push path/to/file
- Push a single file to the remote website.
thm status edit
- Edit and preview this theme in the browser. You must be logged in to see this theme.
thm status publish
- Publish this theme.
thm status publish-managers|publish-hosts
- Publish for all user types, just managers, or just hosts.
From any directory (not just themes)
You can use these commands globally.
thm install
- Configure theme editor environment. Adds files to:
~/.creek-themes/...
thm uninstall
- Remove theme editor environment settings from:
~/.creek-themes/...
thm download 123@example-domain.com
- download the theme folder.
thm list example-domain.com
- list all of the themes at a domain.
thm add-key example-domain.com key-goes-here
- Add a new API key to your user settings for a domain.
thm get-keys
- returns a list of all stored API keys in JSON format from your user settings.
thm get-key example-domain.com
- gets the stored API key for a domain from your user settings.
Random tips
Installing Node.js
On Windows
-
You can use the Windows command prompt to run these same commands. It works the same way Mac, Windows, and Linux.
-
A quick way to get started is to shift + right click on your themes folder and select "Open in Command Prompt".