The purpose of configurations is to make themes easily customizable from the Console without having to touch any code. Configurations may be used to allow the blogger to turn on or off features, change colors and fonts, or even define API keys for external services.

If you are developing a theme for yourself or a single client, you may not want to use configurations. However, if you are planning to publish your theme, adding configurations is required.

All configurations are added to config.yaml with their default values. There are two types of configurations.

All configurations are sent to templates in the _config route variable.

HB-aware Configurations

HB-aware configurations should be written in ENGLISH_UPPER_SNAKE_CASE in config.yaml.

Configuration Description Required Default
THEME_NAME Name of the theme Only if publishing
THEME_VERSION Semantic version of the theme Only if publishing
DEMO_URL Can be used to set a custom demo URL when publishing No Auto-generated
POSTS_PER_PAGINATION Number of posts loaded initially in the _posts route variable No 10

Theme Configurations

Theme configurations (colors, fonts, etc.) should be written in english_lower_snake_case.

config.yaml Example

While you can use multi-nested YAML configs, we recommend to use only upto one nested level.

THEME_NAME: default

dark_theme: Yes
accent_color: 0000000
    api_version: 2

In this example, the first 4 lines are HB-aware configurations. Others are theme configurations. You can add as many theme configurations as you need.


config.def.yaml "describes" your theme configurations (There's no need to describe HB-aware configurations).

This is an example config.def.yaml file that explains the configurations of the previous example.

    $default: Yes
    $title: Dark theme
    $description: Turn on dark theme for this blog
    $type: checkbox

    $default: "#000000"
    $title: Accent Color
    $description: Main color of the blog
    $type: color

    $title: Image Service API Details

        $title: API Key
        $description: ...
        $type: text
             max_length: 255

        $default: 1
        $title: API Version
        $description: ...
        $type: number
             min: 1
             max: 2

We use the config.def.yaml file to render the config.yaml file in Console → Theme as a UI instead of a file. Also, adding conditions in the def file (Ex: min, max) makes sure that wrong configurations are not set by the blogger.

Supported $type s

Types are equivalent to HTML <input> types but have some additions to support other form elements such as <select> out of the box.

These are the supported types:

$type Description
text <input type="text"> . Single-line text input. This is the default, if _type is not defined
textarea <textarea>. Multi-line text input.
checkbox <input type="checkbox"> . Boolean input
radio A radio group. See examples below
select <select> element. See examples below
color <input type="color">. To choose any color
color_palette A color palette with only the given color values. See below
date Date picker
number <input type="number"> Select a number
range <input type="range">

Supported $options

$options Description
$max_length Maximum number of characters in an input
$min Minimum value for an input (for number or range)
$max Maximum value for an input (for number or range)
$step Range step
$required Set if the input is required (cannot be empty)


Use radio input type when you have a limited number of values for a configuration. If you have more than, for example, 3 values, consider using Select instead of Radio. The difference between radio and select is that, radio shows all the options to the user while select only shows the selected value - the user has to click to see other values.

    $title: When to use caching
    $type: radio
         all: For All Posts and Pages
         posts: Only Posts
           pages: Only Pages

When using radio , _values is required, which is takes key: label pairs. key is the actual value that will be saved in the config.yaml file. label is what the user will see.


This is exactly similar to radio. Only the UI is different.

    $title: Font Type
    $type: select
         serif: Serif
         sans: Sans
         sans_serif: Sans-serif

Color Palette

Use a YAML array to define $values.

    $title: Choose a color
    $type: color_palette
    $values: [#000000, #ffffff]


        $title: Choose a color
    $type: color_palette
        - #000000
        - #ffffff

Using Configurations in Templates

After defining configurations, you can use them in your templates. You can access configurations via the _config route variable.

Example: Configurable CSS variables (Taken from our default theme).


  accent: "#896c6b"

  size: 16
  family: "Nunito, sans-serif"

line_height: 24

  radius: 20
  shadow: "0 0 30px rgba(0,0,0,0.05)"

Then, use configs in your templates.

    :root {
        --color-accent: {{ _config.colors.accent }};
        --font-size: {{ _config.font.size }}px;
        --font-family: {{ }};
        --line-height: {{ _config.line_height }}px;
        --box-radius: {{ }}px;
        --box-shadow: {{ }};