Adding new theme settings

Accessing the manifest file

To access the theme manifest file you must export the theme.

The settings are defined within an array in the manifest file and are organized into groups such as Colors. Each setting group is defined using a setting object comprising a label and one or more settings, also known as “variables”.

{
  "name": "Braxton",
  "author": "Zenplates",
  "version": "2.0.0",
  "api_version": 2,
  "default_locale": "en-us",
  "settings": [
    {
      "label": "colors_group_label",
      "variables": [{...}, ...]
    },
    {
      "label": "fonts_group_label",
      "variables": [{...}, ...]
    },
    ...
  ]
}

The value of the “label” properties are translation property names which are defined within files in the translations/ folder of the theme.

After changes are made to the manifest file on your system, you must import the theme in Zendesk Guide in order to have them take effect.

Adding and editing settings

You can edit existing settings or create your own. Each setting group object has the following properties:

The variables array lists the actual settings. Refer to Zendesk’s documentation to learn more about the structure of variable objects and the available setting types.

For example, our themes have two font settings within the Fonts (fonts_group_label) setting group by default: a heading font (heading_font) and body text font (text_font). The heading_font setting contains a large number of predefined Google and web safe font options:

{
  "identifier": "heading_font",
  "type": "list",
  "label": "heading_font_label",
  "description": "heading_font_description",
  "value": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
  "options": [
    {
      "label": "System",
      "value": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif"
    },
    ...
  ]
}

To add a new option in the Heading font dropdown list, create a new object to the options array:

{
  "identifier": "heading_font",
  "type": "list",
  "label": "heading_font_label",
  "description": "heading_font_description",
  "value": "'Webfont', sans-serif",
  "options": [
    {
      "label": "My Webfont",
      "value": "'Webfont', sans-serif"
    },
    ...
  ]
}

Updating the setting value to the value property of your new option object will ensure that your new font is selected by default.

You can add entirely new settings and setting groups as well. For example, to add a new font setting to control the font family of <code> elements you could add the following the to the existing fonts_group_label setting group:

{
  "identifier": "code_font",
  "type": "list",
  "description": "code_font_description",
  "label": "code_font_label",
  "value": "SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace",
  "options": [
    {
      "label": "System",
      "value": "SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace"
    },
    {
      "label": "Courier New",
      "value": "'Courier New', Courier, monospace"
    }
  ]
}

The value of that setting can then be used in CSS and HTML, for example:

code {
  font-family: $code_font;
}