Skip to main content


Your theme can define additional variables that are made available in the global context under the theme attribute. To define variables add them to your theme.json file in the following format.

  "name": "Amazing Coffee Theme",
  "version": "1.1.3",
  "engine": "1.0.0",
  "variables": [
      "key": "facebook_url",
      "title": "Facebook profile URL"
      "key": "twitter_username",
      "title": "Twitter username",
      "help_text": "Used for Twitter Card support, e.g. @amazingcoffee"
Name Type Description
variables list A list of the defined variables.
variables[].key str A key that is used for the variable in the context. This key can only contain lowercase letters, numbers and underscore characters. Max length is 50 characters.
variables[].title str A title that is displayed in the Dashboard identifying the variable. Max length is 50 characters.
variables[].help_text str Optional help text displayed in the Dashboard to further describe the use of the variable. Max length is 150 characters.

When a user uploads a theme that defines additional variables the corresponding fields are made available in their site settings. The user can then provide values to these variables which are passed in to the context and made available to the theme.

Template Example

The following example shows how to access a defined variable from a theme template. As the user may not have provided a value you must first check before using it.

{% if theme.variables.twitter_username %}
  <meta name="twitter:creator" content="{{ theme.variables.twitter_username }}">
{% endif %}

Common Keys

The values provided by a user in the Dashboard are preserved when switiching themes. This allows a user to change themes and if the variable keys are the same, e.g. twitter_username, then they don’t have to re-enter the value again. Before defining your own keys we strongly recommend you check the following common keys lists and use one of them if it’s for a service you wish to provide in your theme.


  • 500px_username
  • adn_username
  • behance_username
  • bitbucket_username
  • codepen_username
  • dribbble_username
  • facebook_url
  • flickr_username
  • github_username
  • instagram_username
  • linkedin_url
  • pinterest_username
  • reddit_username
  • soundcloud_username
  • spotify_username
  • steam_username
  • tumblr_username
  • twitch_username
  • twitter_username
  • vimeo_username
  • vine_username
  • youtube_username


  • clicky_code
  • convertkit_code
  • disqus_shortname
  • feedpress_url
  • google_analytics_code
  • gosquared_code
  • itunes_affiliate_id