Working on a theme locally

What's my plan?

All Suites | Growth, Professional, Enterprise, or Enterprise Plus

Support with | Guide Professional or Enterprise

The most powerful help center theming features 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 Knowledge admin.

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.

Downloading your theme

Now you're ready to download your theme from Knowledge admin. A theme is downloaded as a zip archive of templates, JavaScript, CSS, and assets. This enables you to work on the theme outside of Knowledge admin, 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 Knowledge admin 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 Knowledge admin from GitHub. See Setting up the GitHub integration with your help center theme.

Importing your theme

After you’ve built out the theme locally, compress the theme directory into a ZIP archive and import it into Knowledge admin 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 it further in Knowledge admin, 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 Knowledge admin from GitHub. You don't need to create a separate ZIP archive and import it. See Updating your GitHub-managed theme in Knowledge admin.

Another option is to build your own integration with the Themes API to import and update themes in Knowledge admin. 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 Knowledge admin. Check in your changes and import the theme into Knowledge admin again. If you accidently make changes to your theme in Knowledge admin, download the updated theme and check those changes into your source control system.

Important: If you set up an integration with GitHub, making any modifications to your theme in Knowledge admin will break the GitHub integration.