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.
The purpose of configurations is to make themes customizable to some extent without having to change the theme 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 accessible in templates from the _config
route variable.
HB-aware configurations should be written in ENGLISH_UPPER_SNAKE_CASE
in config.yaml
.
THEME_NAME
- Name of the themeTHEME_VERSION
- Semantic version of the themeTHEME_FONTS
- Fonts to load in the blog. See fonts.DEMO_URL
- Can be used to set a custom demo URL when publishingPOSTS_PER_PAGINATION
- Number of posts loaded initially in the _posts
route variableTheme configurations (colors, fonts, etc.) should be written in english_lower_snake_case
.
While you can use multi-nested YAML configs, we recommend to use only up to one or two nested level.
THEME_NAME: hello
THEME_VERSION: 1.0.0
THEME_FONTS: "mulish:400,700"
POSTS_PER_PAGINATION: 15
dark_theme: Yes
accent_color: 0000000
image_service:
api_key:
api_version: 2
In this example, the first 3 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. This helps the blogger to understand what each configuration does. It also helps to render the config.yaml
file in Console → Theme as a UI instead of a file.
Test your config definitions at blogs.hyvor.com/config.
This is an example config.def.yaml
file that explains the configurations of the previous example.
dark_theme:
$name: Dark theme
$description: Turn on dark theme for this blog
$type: checkbox
accent_color:
$name: Accent Color
$description: Main color of the blog
$type: color
image_service:
$name: Image Service API Details
api_key:
$name: API Key
$description: ...
$type: text
$maxlength: 255
api_version:
$name: 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.
These are the supported definitions for theme configurations:
$type
- Type of the configuration. See Supported $type
s.$name
- Name of the configuration.$description
- Description of the configuration.$minlength
- Minimum number of characters in an input.$maxlength
- Maximum number of characters in an input.$min
- Minimum value for a number.$max
- Maximum value for a number.$type
sThese are the supported types for theme configurations:
$type
none
text
$type
is not definedtextarea
number
checkbox
radio
color
You can set radio options in $options
, which is a key: label
pair list. key
is the actual value that will be saved in the config.yaml
file. label
is what the user will see.
some_key:
$title: When to use caching
$type: radio
$options:
all: For All Posts and Pages
posts: Only Posts
pages: Only Pages
After defining configurations, you can use them in your templates. You can access configurations via the _config route variable.
Example: Configurable CSS variables.
config.yaml
:
colors:
accent: "#896c6b"
font:
size: 16
family: "Nunito, sans-serif"
line_height: 24
box:
radius: 20
shadow: "0 0 30px rgba(0,0,0,0.05)"
Then, use configs in your templates.
<style>
:root {
--color-accent: {{ _config.colors.accent }};
--font-size: {{ _config.font.size }}px;
--font-family: {{ _config.font.family }};
--line-height: {{ _config.line_height }}px;
--box-radius: {{ _config.box.radius }}px;
--box-shadow: {{ _config.box.shadow }};
}
</style>