I hope everyone had a good break over the holidays. I know I caught up on some much-needed rest and am now excited to get back into the swing of doing fun things with WordPress themes.
Now it’s time to discuss the current progress and next steps of one of our biggest projects of 2024: the Theme Handbook overhaul.
What Is the Theme Handbook Overhaul?
This is a project that the theming community agreed to take on last year. Its goal was to give the Theme Handbook content a refresh, primarily focusing on modern block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. theme development.
You can read the initial proposal and previous project updates here:
The ongoing work is tracked via the Theme Handbook Overhaul tracking ticket on GitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/.
The Project’s Progress
In 2023, five new/updated chapters were published in the handbook:
The primary focus of these first five chapters is to introduce theme creators to the block theming system. Most of this documentation is 100% new. If you haven’t browsed the handbook for a while, now is a great time to catch up!
There are also eight draft articles that have yet to be published.
In terms of “chapter count,” that’s nearly half of the project. But if looking at the actual new content that needed to be created, it’s probably closer to 2/3 of the way toward the finish line.
The Next Steps
The plan is to complete the entire overhaul by the end of Quarter 2 (June 30) of 2024. I believe we can get the bulk of the new content published or drafted in Q1, leaving most of Q2 for final touches and cleanup.
In the coming months, there are still six chapters left to create or update:
- Patterns (recently added to the outline)
- Classic Themes
- Advanced Topics (mostly drafted)
- Accessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility)
- Guides
- Contributing
The Classic Themes, Advanced Topics, and Guides chapters are mostly content updates and a bit of reorganization. These are what I’d call “good first issues” for anyone who wants to contribute but is not ready to write a full documentation article on their own.
The Patterns chapter was recently added to the outline because patterns are a first-class tool in WordPress that will only continue to become more powerful. There is currently a single Block Patterns doc, but it needs to be expanded into multiple articles that showcase each pattern feature. If you like to tinker with patterns, this could be a fun chapter to contribute to.
One area where the project really needs a volunteer is for the Accessibility chapter. It’d be great to have an expert in the field to review and expand upon the existing documentation.
Get Involved
To get involved, all you need to do is:
You can reach out for help with this in the #docs or #themereview Slack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channels. You can also ping The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me (@greenshady) directly if you have questions.
Props to @kafleg for reviewing this post.
#theme-documentation
