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 are 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 each change locally in a web browser using the Zendesk apps tools, (ZAT). The goal of the local preview is to enable theme developers to work with the tools they’re familiar with to build themes quickly and easily. To set up ZAT theme preview, see Previewing theme changes locally.
After you start preview mode, you can modify your theme files in your favorite text editor. The local preview has live reload. Changes you make to files will automatically refresh the preview. From here, you can quickly make changes to templates, CSS, JavaScript, and assets.
Additionally, when you have downloaded a theme to your local machine, it's a good idea to check it into your favorite version control repository, such as git, mercurial, SVN, etc.
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.
5 Comments
When I preview my theme via $zat theme preview and paste the /start link in my Chrome URL, I receive a 'blocked by CORS policy' error in the console. The origin is my own subdomain URL as expected, and it attempts to fetch at *myMappedDomain*/hc/activity. , which is a URL that throws a 404 error so as far as I can tell, the theme loads trying to fetch data from a page that doesnt exist. This is not part of our code in the templates.
I did allow for mixed contents to be loaded as per a this article, but there is no mention specifically about the CORS issue.
While I do use ZAT Tools in this case the troubleshooting step of the Troubleshooting CORS article:
As part of the Apps framework, a back-end proxy server is available via the client.request() call. Use this proxy by setting cors:false in the client.request's settings (note: false is also the setting's default value).
does not help since I have the "special case" of previewing the Zendesk Theme which I downloaded from the Guide, there are no explicit client requests being made in the theme files .
/thanks,
Diego
Hi Diego,
We have the CORS Troubleshooting that will surely help you find a solution for this issue.
All the best
"Important: If you set up an integration with GitHub, making any modifications to your theme in Guide will break the GitHub integration."
Is there any way to reverse this?
As it turns out, the only method is to perform the integration again once it breaks.
Hi All,
We are looking to talk to people that have code customized a Help Center theme or tried and failed to code-customize a theme.
If you are up for sharing your feedback through a 30 min video interview, please sign up and answer 3 short survey questions at the end of the form. We would love to hear from you!
Sign up here.
Looking forward to talking to you!
Gorka Cardona-Lauridsen
Sr. Product Manager, Zendesk Guide
Please sign in to leave a comment.