New plugin to write WordPress theme JSON files via YAML – WP Tavern
I have a new favorite WordPress development related plugin: YAML Theme. Sascha Paukner published it just a day ago, and it might find its way into many theme developers’ toolkits before long. It allows themists to write JSON themes in YAML format.
To use it, theme authors simply create a new
theme.yaml file and start adding their custom configuration in friendly YAML format. The plugin will convert it to JSON and save it to the
As someone who’s had their fair share of headaches writing directly to JSON, I’ve never been happier looking at the following in my code editor:
I just wish I had thought of this plugin idea first. I regularly work with YAML files when dealing with other systems and convert data to PHP and JSON. It made sense as soon as I saw the description of the plugin.
JSON is not the easiest format to write when dealing with configuration files, which
theme.json file is. This works well for multi-language data storage, but sometimes I cringe when I open a JSON file for input, especially if it has hundreds or thousands of lines. Additionally, you may not leave online comments to remind yourself or others why a particular decision was made or setting configured.
Is YAML better? This has its pros and cons, and in my experience some parts of the syntax can get tricky for unfamiliar people. However, online comment support is worth it.
The documentation for the plugin was simple at best. He didn’t say anything about how it worked under the hood. I had questions. Is there a parameter for conversion? Is it automatic? Does this happen on every page load?
I made a pic under the hood so you don’t have to. The plugin automatically searches for a
theme.yaml file in the root folder of the active theme when a page is loaded. If found, it will check its last modification time and store the value in the database. If there are new changes, the plugin analyzes
theme.yamlconverts it to JSON and writes it to the
If the active theme is a child, it will also automatically perform this process for its parent.
The downside of the plugin is that it leaves the resulting JSON minified, which is hard to read. It’s OK when you have the
theme.yaml file at your fingertips. However, when submitting to the WordPress.org theme directory, this “build” file would typically be something that a theme author would not bundle in their theme ZIP.
I’m a big believer in shipping code readable and editable by anyone who receives a copy. There are several options for theme authors to do this. They can ship both the
theme.yaml files or edit the following code in the main plugin file:
$themeJson = json_encode($themeObject, JSON_UNESCAPED_SLASHES);
We just have to switch to the
JSON_PRETTY_PRINT flag for the
json_encode() a function:
$themeJson = json_encode($themeObject, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT);
I hope the plugin developer will consider this change in a future release or allow theme authors to filter it.
There are other solutions for theme authors who are hesitant to
theme.json. I’ve split my JSON into manageable chunks across multiple files in the past. Then I used a webpack plugin to merge them during my monitoring/build process.
I recommend using the JS YAML parser or a similar package for those who prefer YAML but want integration with their build system.