The most powerful theming features in Guide are the abilities to import, download, and work locally with themes. When you’re making major updates to a theme or building your own theme from scratch, these options enable a streamlined workflow for developers.
The workflow to build a new theme or update an existing theme locally is as follows:
- Starting a new theme by adding the Copenhagen theme or duplicating an existing theme.
- Downloading your theme to work offline.
- Editing your theme locally locally with your own development tools.
- Importing your theme back into Guide.
- Publishing your new theme.
- Making additional updates.
Starting a new theme
If you’re building a brand new theme from scratch, consider starting from a new version of the standard Copenhagen theme. To do so, you add a new theme and a fresh copy of the Copenhagen theme is added to your Themes page. You can also get a fresh version of the theme from the open-source Copenhagen repository on GitHub.
Many people like to start with an existing theme and make major modifications to create their own theme. If you’re revamping an existing theme and want to keep some of the existing styles, you can duplicate the theme.
To start a new theme by adding a fresh copy of Copenhagen or by copying an existing theme, see Adding a help center theme to Guide.
Downloading your theme
Now you're ready to download your theme from Guide. A theme is downloaded as a zip archive of templates, JavaScript, CSS, and assets. This enables you to work on the theme outside of Guide, using your own development tools.
To download your theme, see Downloading a help center theme.
Editing your theme locally
Now you’re ready to start working on your local machine, using your own development tools.
To avoid zipping and importing the files into Guide every time you want to preview your changes, you can preview changes locally in a web browser. To set up local theme previewing, see Previewing theme changes locally.
Once set up, you can preview changes locally by saving the files you're working on. The theme reloads automatically in the browser. This lets you work iteratively, making changes to templates, CSS, JavaScript, and assets, and then previewing the results of your work.
Additionally, when you download a theme to your local machine, it's a good idea to check it into your favorite version control repository, such as git, mercurial, or SVN.
Your team can also develop and maintain the theme collaboratively using GitHub, then preview or publish it in Guide from GitHub. See Setting up the GitHub integration with your Guide theme.
Importing your theme
After you’ve built out the theme locally, compress the theme directory into a ZIP archive and import it into Guide by dragging and dropping the file on the Themes page or by using the import option.
This will import the theme as a new custom theme. You can preview further in Guide, and other users in your organization will also be able to see the theme.
To import your theme, see Importing a help center theme.
If you set up an integration with GitHub, you can update a theme in Guide from GitHub. You don't need to create a separate ZIP archive and import it. See Updating your Github-managed theme in Guide.
Another option is to build your own integration with the Themes API to import and update themes in Guide. See Theme Import Workflow and Theme Update Workflow in the Zendesk developer docs.
Publishing your new theme
When you're ready to publish your new theme, just click Publish from the theme menu in the workbench.
Making additional updates
If you're using version control systems like git or mercurial, continue making changes locally, not in Guide. Check in your changes and import the theme into Guide again. If you accidently make changes to your theme in Guide, download the updated theme and check those changes into your source control system.