Runnable Code Examples Land in WordPress Code Reference

🇹🇷 Türkçe: Bu yazının Türkçesini oku →

The first computer I owned, around 1990, came with a QuarkXPress manual heavier than the machine itself. When something didn’t behave the way the docs implied, my only option was to open a fresh document and try. Half of what I know about typography lives in that little “let me just try it” gap between reading and doing.

Web documentation has been slowly closing that gap for years. MDN runs JavaScript in the page. Rust has a Playground button on almost every function reference. PHP’s own manual has, for two decades, mostly ended with user-contributed comments saying “here is what actually works.” WordPress, until this week, still asked you to spin up a local install to find out what any given function did on a real site.

That changed on September 4. Not with a bang, not on a release-day slide deck. A small commit in the Code Reference and one Make/Core post, and suddenly you can click a Run button on WP_HTML_Processor::class_list() and watch the code execute against a live WordPress inside your browser tab. This is the kind of change I care about — small on the surface, load-bearing underneath.

What is actually new

Adam Zieliński’s Make/Core post “Runnable code examples are now live in the Code Reference”, published September 4, 2026, ships the first two runnable examples on developer.wordpress.org. WordPress 7.1 introduced the plumbing; 7.2 will bring more examples across the reference. You can see it live on the WP_HTML_Processor::class_list() reference page — a Run button, an editable code block, real output rendered underneath the snippet.

The mechanism is deliberately minimal. Contributors add a code fence to the DocBlock of the target function or method with a special tag:

```php interactive
<?php
$processor = WP_HTML_Processor::create_fragment( '<div class="a b c">Hi</div>' );
$processor->next_tag();
var_export( iterator_to_array( $processor->class_list() ) );
```

The interactive marker is what the phpdoc-parser picks up. Developer.wordpress.org then renders that fenced block through the <php-snippet> web component from WordPress Playground. On first Run, Playground lazy-loads a full WordPress plus PHP 8.4 runtime inside a hidden iframe, and every subsequent snippet on the page reuses the same runtime — so the second click is essentially instant.

The primitive underneath is not new. Playground’s <php-snippet> component shipped in May 2026 and is documented in the Playground handbook. You embed it with a single script tag, add wp="none" for pure-PHP snippets, or require '/wordpress/wp-load.php' when you want the full stack; expected output can be pre-declared, and there is even a Ctrl+Enter shortcut for the muscle-memory crowd. What ships this week is the wiring: the parser reads the interactive fence out of the DocBlock, and the reference page renders it. The two habits — writing the docs and running the docs — finally live in the same place.

Credit in the announcement goes to @jonsurrell, @dmsnell, and @westonruter. The authored example lives in class-wp-html-processor.php in the wordpress-develop repository. A handbook page with full authoring guidelines is being prepared for the next cycle.

Why it matters for WordPress and WooCommerce people

Two things.

First, documentation quality. Every senior WordPress developer I know has, at some point, misused a core function because the DocBlock said one thing and the runtime did another. The HTML API in particular is the kind of surface where you can read the signature ten times and still guess wrong about what class_list() returns for a virtual node. A Run button turns that guessing into a two-second experiment. Multiply that across the thousands of functions in the reference — with 7.2 promising broader coverage — and the marginal cost of learning any given part of core drops noticeably.

Second, this is a very quiet consolidation of Playground as core infrastructure. WordPress Playground is no longer a curiosity you use to reproduce a bug in a plugin thread. It is the runtime Learn WordPress uses for interactive lessons, the runtime the Documentation-Issue-Tracker proposal #730 laid out for testable docs, and now the runtime the official reference embeds. If you are building anything on top of Playground — training materials, sales demos, a “try before you buy” flow for a WooCommerce extension — you are on the same rails as core.

For WooCommerce authors specifically, this is the model to copy. Nothing stops a plugin’s own documentation site from dropping in the same <php-snippet> component pointed at a store-preloaded blueprint. A prospective customer clicking Run on your extension’s docs and seeing it actually work against a live cart is a stronger demo than any screenshot in a gallery.

What I would do (or not do) about it

I would treat this as permission to raise the bar on my own documentation. Three concrete moves:

• Adopt <php-snippet> in plugin docs where the example is short. One script tag, and snippets that used to be inert prose become verifiable. Not everywhere — a snippet that mutates a real order table is not something to run in a demo runtime — but for filter and action examples and small utility functions, this is a free upgrade.
• When contributing to core, write DocBlock examples in the interactive style from day one. Every merged patch that adds a public API is a chance to leave the reference a little better than you found it.
• Stop linking to random third-party “how does X work” blog posts in internal handovers. The reference page itself now runs. Send the link, close the tab.

What I would not do: rush to rewrite years of documentation in a weekend. The whole point of the interactive tag is that it is additive. Existing static examples keep working. Add the runnable version where it earns its keep — usually the surfaces that trip people up — and leave the rest until the handbook guidelines land in 7.2.

The one caveat is content security policy. Sites with a strict CSP will need to allow https://playground.wordpress.net for both script and iframe sources. If your docs site is behind an aggressive CSP header, that is a one-line change; if it is behind a compliance team, budget a week.

Twenty years in, the pattern I have seen repeatedly is that a documentation improvement compounds slowly and then all at once. Runnable examples are the kind of upgrade nobody notices for a quarter, and then nobody can imagine going back.