You can export a theme's files from Guide and work on the files offline in your favorite editor. 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). To preview a change, you simply save the theme file in your desktop editor and refresh the page in the browser. Example:
ZAT is a collection of developer tools that includes Sinatra, a web server that runs locally on your computer. After starting the preview mode, the process runs in the background. See the command-line interface on the lower side of the image.
Topics covered in this article:
Setting up local theme preview
To set up local theme preview
- If not already done, enable API access in your Zendesk Support account by going to Admin > Channels > API.
- Install the Zendesk apps tools, (ZAT).
See Installing and using the Zendesk apps tools in the Develop help center.
- If you previously installed ZAT to build Zendesk apps, make sure to update it by running the following command in your command-line interface:
$ gem update zendesk_apps_tools
To install and use ZAT, you'll need a command-line interface, (CLI). In macOS, you can use Terminal in the Applications/Utilities folder. In Windows, you can use the command prompt or Powershell. If you're a Windows 10 user, you can install and use a Bash shell, a more developer-friendly CLI. See Setting up a Bash shell in Windows 10.
Starting local theme preview
You should start local theme preview before you start working on theme files on your computer.
To start local theme preview
- In your command line interface, navigate to the folder containing the exported and unzipped theme files.
Use the cd command (for change directory), to navigate to a child folder. Example:
$ cd guide_themes/newlook_theme
To back up one directory, use cd followed by a space and two periods. Example:
cd ..
- Run the following command:
$ zat theme preview
- At the prompts, enter your Zendesk Support subdomain, as well as the email and password you use to sign in to Zendesk Guide.
The subdomain and email are saved in a text file named .zat in the theme's folder so that you only need to enter your password the next time you start preview mode. If you make a mistake entering your username or password, delete the .zat file and start again. Note that files with leading periods are hidden in macOS by default. See Show Hidden Files in Mac OS X on the osxdaily.com website.
If you use single sign-on (SSO) to sign in to Guide (such as using Google or Microsoft credentials), you can sign in using an API token that you can get from the Support admin interface. See API token in the REST API docs. When prompted by ZAT to sign in, enter {your_email}/token for your user name, where "/token" is the actual string "/token". Use the actual API token for your password. Example:
Enter your username: jdoe@example.com/token Enter your password: e8Pvy0pvGzE8meUQxWgjIYkjr
After successfully signing in, preview mode starts and runs in the background:
- Copy the "Ready" URL in the output and paste it in a browser.
In the example, the URL is https://nadosolutions.zendesk.com/hc/admin/local_preview/start.
An unformatted page loads after you sign in. Modern browsers have a security feature that blocks certain local files (known as mixed content) from loading in a page. You can disable the feature in Chrome and Firefox as described in the following step.
- In Chrome or Firefox, click the shield icon in the Address bar and agree to load an unsafe script (Chrome) or to disable protection on the page (Firefox). In Firefox, the shield icon is located on the left side of the Address bar.
Note: Safari has no option to disable protection. You must use Chrome or Firefox for previewing.
The correctly formatted page should load automatically. You can start editing theme files in your editor and previewing changes locally in the browser.
Previewing changes
After starting the theme preview mode, you can work on your theme files in your favorite editor. Work iteratively to develop and test your theme. For example, make some changes to your JavaScript, save the changes, then refresh the browser page to test the changes.
To preview changes
- Save the edited file in your editor.
- Refresh the page in the browser.
When you're done for the day, you can stop preview mode using one of the following methods:
- Switch to your browser and click the "To exit, click here" link at the top of the previewed page.
- Switch to your command-line interface and press Control+C.
19 Comments
I have a problem, i think, with livereload and ZAT.
If a launch Zat Theme Preview my pages are unformatted and slowly, the console show this:
and some others.
I have allowed the Insecure Content on Chrome and also test with zat theme preview --no-livereload but doesn't work.
I must work with online data, on our guide, but it seems impossibile!
There is a work around for this problem?
Thanks a lot
Hi Pasquale! For an issue like this, I would recommend reaching out directly to our Advocacy team so that they can get additional information needed to assist here.
Just wanted to reach out here to see if anyone has been running into issues with the ZAT when trying to work on themes locally. For some reason it's not picking up changes to template files any more and I have to close down and rerun zat theme preview for every change.
One of my team also is getting intermittent issues where it's taking ages to fully spin up with web server which is doubly annoying given the above.
Hi, I had same problems over 1 year ago. The API for local development is just bad. I created custom solution for it because I spent 2 weeks trying to make it fully work. No chance. Server breaking connection, continuous problems with uploads etc. I created own continuous deployment scripting in Gulp. It is working and I advice to do the same. Zendesk API allowed to do it all by myself.
Trying to set this up and the first step is a show stopper, it says:
However, when I go to Admin > Channels there is no API and there is no way to add API. Did something change in how to configure this?
Hi Keith,
You can access API by going to Admin(the one that looks like the wheel icon on the left side of the screen)>Channels>API. If you are still unable to see it, you may reach out to our Customer Support so they can have a closer look into your account
I have host mapping enabled, and when I navigate to the URL generated by theme preview, I'm redirected to the specified host mapping. When I set the domain to the specified host mapping, navigating to the generated URL still redirects. What is the recommended means of previewing themes when using host mapping?
Hi Joshua,
When previewing your Help Center, you can also go to your Guide Admin>Themes>Them that you would like to preview> On the preview page, you can choose the Template and the preview role can be changed from end-user to admin
**Never-mind, it's now inexplicably working.**
Weird. I posted this message on Friday and it's missing now.
I'm working on setting up my local Zendesk Guide theme so I can make some changes. I've followed the instructions here, but when I do step 4 "Copy the "Ready" URL in the output and paste it in a browser." the help center just redirects to my main Guide page. Am I missing something?
Hello,
When I use the command
and enter all the details, the server starts, but then immediately stops with runtime error
What can I do to fix this error?
Any help appreciated, since I am new to Zendesk.
Thanks,
Arati
Is it possible you ran into issues bring the server up before this try? The error suggests that the port is taken by a process already.
You can get a list of ports using this cmd on linux:
sudo lsof -i -P -n
if the Zendesk one is open or in use you can kill the process taking the port using this.
kill -9 $(lsof -t -i:8080)
Another option is logging out and back in or a restart to free up the port.
Thank you Ben, it worked, after I restarted the system.
Next, I am running into issue like Trey above. Even if I am using the "Ready URL" I am being redirected to the main page of my guide and the URL is that of the active Zendesk site. It says it is preview mode, is that the right way like in screenshot? but the URL is not the one which I entered with preview start. Am I missing something?
Thanks,
Arati
when you visit the ready URL it always redirects back to the homepage and you get the banner you are seeing there. This should mean you are correctly in the preview and edits you make should be reflected now.
You can confirm by checking your script assets are coming from local sources.
Hi Pawel Przysucha,
Thanks for reaching out!
If you’re accessing the theme preview from a browser in which your credentials aren’t saved or you’re not logged in, the preview will still require sign-in if this is a setting in your account.
Let me know if you have any questions!
Tipene
Hi Paweł Porombka,
I just read your comment:
"The API for local development is just bad. I created custom solution for it because I spent 2 weeks trying to make it fully work. No chance. Server breaking connection, continuous problems with uploads etc. I created own continuous deployment scripting in Gulp. It is working and I advice to do the same. Zendesk API allowed to do it all by myself."
I'm really curious about how you solved those issues. Would you maybe write a community post that explains how you created your custom solution? I hope so! Thanks :)
Or, it would be great if we could get guidance from Zendesk on those issues with ZAT theme preview. It's really slowing down our development :/
Hi Gizem! Could you let me know what filesystem you're using? We use the `listen` gem for ZAT, which does have some limitations related to the fs that it's being run on. There is an open PR on the ZAF repo to force polling, which could potentially resolve this, but with it being in maintenance mode right now, it's difficult to get traction on moving that forward. I'll see what I can do though!
Hi Greg,
Thanks for taking a look at this! My filesystem seems to be "APFS (Encrypted)".
I hope you can get the PR moving and that can fix the issues with previewing! 🤞🙏
Please sign in to leave a comment.