Working on a theme locally

Article author
John Smith

The most powerful theming features in Guide are the abilities to import, export, and work locally with themes. When you’re making major updates to a theme or building your own theme from scratch, these great options enable a streamlined workflow for developers.

You must have Guide Professional or Enterprise to work on a theme locally.

The workflow to build a new theme or update an existing theme locally is:

  1. Start a new theme by adding the Copenhagen theme or duplicating an existing theme.
  2. Export your theme to work offline.
  3. Edit your theme locally with your own development tools.
  4. Import your theme back into Guide.
  5. Publish your new theme.

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. Otherwise, if you’d like to check out a version of it from GitHub locally, our open source Copenhagen repository can be found here.

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 duplicating an existing theme, see Adding a Help Center theme to Guide.

Exporting your theme

Now you are ready to export your theme. A theme is exported 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 export your theme, see Exporting 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 exported a theme to your local machine, it’s a good idea to check it into your favorite version control repository (git, mercurial, SVN, etc.).

Importing your theme

Once 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 export your theme, see Importing a Help Center theme.

Publishing your new theme

When you are ready to publish your new theme, just click Publish from the theme menu in the workbench.

Remember, if you are using version control and you’ve made any code modifications to your theme in Guide, export the latest version and check those changes into your repository.

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request



Be the first to write a comment.