New Plugin for Writing WordPress Theme JSON Files via YAML – WP Tavern

Justin Tadlock
I have a new favorite WordPress development-related plugin: Theme YAML. Sascha Paukner released it a mere day ago, and it may find its place in many theme developers’ toolboxes before long. It allows themers to write theme JSON in YAML format.
To use, theme authors only need to create a new theme.yaml file and begin adding their custom configuration in the human-friendly YAML format. The plugin will convert it into JSON and save it to the theme.json file.
As someone who has had his fair share of headaches writing directly in JSON, I have never been happier to look at the following in my code editor:
That is pretty.
I just wish I had thought of this plugin idea first. I routinely work with YAML files when dealing with other systems and convert the data to PHP and JSON. It just made sense as soon as I saw the plugin description.
JSON is not the easiest-to-write format when dealing with configuration files, which is what the theme.json file is. It works well for cross-language data storage, but I sometimes cringe when opening a JSON file to type in, especially if it has 100s or 1,000s of lines. Plus, you cannot leave inline comments to remind yourself or others why a particular decision was made or a setting configured.
Is YAML better? It has its pros and cons, and in my experience, parts of the syntax can become complex for the unfamiliar. However, supporting inline comments alone is worth it.
The plugin’s documentation was bare-bones at best. It said nothing about how it worked under the hood. I had questions. Is there a setting for the conversion? Is it automatic? Does it happen on every page load?
I peaked under the hood so that you do not have to. The plugin automatically searches for a theme.yaml file in the active theme’s root folder when a page is loaded. If found, it will check its last modified time and store the value in the database. If there are new modifications, the plugin parses theme.yaml, converts it to JSON, and writes it to the theme.json file.
If the active theme is a child, it will also automatically run through this process for its parent.
The downside to the plugin is that it leaves the resulting JSON minified, which is tough to read. This is OK when you have the theme.yaml file on hand. However, when submitting to the theme directory, this “build” file would typically be something a theme author would not bundle in their theme ZIP.
I firmly believe in shipping code that is readable and editable to whoever receives a copy. There are a couple of options for theme authors to do this. They can ship both the theme.json and theme.yaml files or change the following code in the plugin’s main file:
We merely need to toggle on the JSON_PRETTY_PRINT flag for the json_encode() function:
I hope the plugin developer will consider this change in a future version or allow theme authors to filter it.
There are other solutions for theme authors who shy away from theme.json. I have split my JSON into manageable chunks across multiple files in the past. Then, I used a webpack plugin for merging them during my watch/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.
Dear Justin,
thank you for your kind review of the plugin. I’m amazed how quickly you got this done!
I will add a filter, how you suggested, to make sure the generated theme.json more readable. I left it intentionally a one liner to make sure people are aware that it is generated.
I’ll also beef up the documentation in the coming days.
If you have any other suggestions let me know.
Awesome! And, thanks for providing such a useful tool.
JSON has an advantage over YAML in that you can have a schema defined that will help with autocompletion and validation.
Ideally, configs should be written in PHP (like Symfony is doing in v6), as you can cache the calls in the opcache plus you can have autocompletion in the IDE. The problem is that you need to expose them in JS somehow for the blocks/editor. But that’s an implementation detail.
Agreed. I’d like to write configs in PHP. If I have the time and no one beats me to it, I might just write a Composer script to run from the command line, converting theme.php to theme.json.
It’d be neat to have a command to convert PHP, YAML, or even NEON to JSON.
From the PHP end, you could probably use NetteSchema for validation.
Excellent everything I read in this blog, it helps me a lot, thank you very much!
Your email address will not be published.

document.getElementById( “ak_js_1” ).setAttribute( “value”, ( new Date() ).getTime() );
This site uses Akismet to reduce spam. Learn how your comment data is processed.
Enter your email address to subscribe to this blog and receive notifications of new posts by email.

WordPress Tavern is a website about all things WordPress. We cover news and events, write plugin and theme reviews, and talk about key issues within the WordPress ecosystem…
© All Rights Reserved. Powered by WordPress, hosted by Pressable


Leave a Reply

Your email address will not be published. Required fields are marked *