Previewing theme changes locally

You can export a theme's files from Guide and work on the files offline in your preferred text 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 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.

Note: The Zendesk Command Line Interface (ZCLI) replaces ZAT for app development but does not support previews for Zendesk Guide themes yet.

Topics covered in this article:

• Setting up local theme preview
• Starting local theme preview
• Previewing changes

Setting up local theme preview

To install and use ZAT, you'll need to enable API access and set up a local development environment.

To set up local theme preview

1. If not already done, enable API access in your Zendesk Support account by going to Admin > Channels > API.
2. Install ZAT. See Installing and using ZAT in the Zendesk developer documentation. Then return here.
3. Update ZAT by running the following command in your computer's terminal:

   gem update zendesk_apps_tools

Starting local theme preview

Start the local theme preview before you start working on theme files on your computer.

To start local theme preview

1. In your computer's terminal, navigate to the folder containing the exported and unzipped theme files. Example:

   cd guide_themes/newlook_theme

2. Run the following command:

   zat theme preview 

3. At the prompts, enter your Zendesk subdomain, as well as the email and password you use to sign in to Zendesk Guide.

   

   If you use single sign-on (SSO) to sign in to Guide, you can sign in using an API token. 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 API token for your password. Example:

   Enter your username: [e-mail]/token
   Enter your password: e8Pvy0pvGzE8meUQxWgjIYkjr

   After successfully signing in, preview mode starts and runs in the background:

   

4. Copy the "Ready" URL in the output and paste it in a web browser, such as Chrome or Firefox. The browser must allow mixed HTTP and HTTPS content. Safari doesn't support mixed content and won't allow you to preview themes locally.

   In the example, the "Ready" URL is https://z3n-example.zendesk.com/hc/admin/local_preview/start.

   The URL should load the theme preview.

Previewing changes

After starting the theme preview mode, you can work on your theme files locally in your text 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

1. Save the edited file in your text editor.
2. Refresh the page in the browser.

When you're done, you can stop preview mode using one of the following methods:

• In the terminal session running ZAT, press Ctrl+C.
• At the top of the browser's theme preview page, click the Close preview link.