WordPress · adamziel · May 3, 2026 · May 3, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -9,6 +9,9 @@ into WordPress plugins under `plugins/`.
 
 Upstream: https://github.com/WordPress/php-toolkit
 Branch: `trunk` (not `main`)
+Docs site: https://wordpress.github.io/php-toolkit/ — runnable examples per
+component, sourced from `bin/_docs_components/<slug>.md`. Edit those files
+to change the snippets that ship and the captured output that CI verifies.
 
 ## Commands
 

diff --git a/README.md b/README.md
@@ -1,17 +1,36 @@
 ## PHP Toolkit
 
-Standalone PHP libraries for use in WordPress plugins and standalone PHP projects:
-
--   XMLProcessor – stream-parse XML files on any PHP installation (no libxml2 required).
--   Git – a pure PHP implementation of Git client and server.
--   HttpClient – a streaming, non-blocking, concurrent HTTP client library with no curl dependency.
--   Zip – stream-parse and stream-write ZIP files with no libzip dependency.
--   Data Liberation – generic streaming data importers to WordPress. Supports WXR, zipped markdown, remote git repos, rewriting URLs, and more.
--   ByteStream – composable byte streaming utilities – readers, writers, filters.
--   Markdown – convert between markdown and block markup with no dependencies.
--   Filesystem – single API for working with local files, Git, Google drive, memory, etc.
-
-This fork consolidates a few earlier projects and explorations into a single composer package.
+<!-- docs-site-banner -->
+> 📚 **Live, runnable docs:** **<https://wordpress.github.io/php-toolkit/>**
+> Every component has a reference page with snippets that execute in WordPress Playground — edit code in your browser, click *Run*, see real output. There's also a short [learning path](https://wordpress.github.io/php-toolkit/learn/).
+<!-- /docs-site-banner -->
+
+Standalone, dependency-free PHP libraries for use in WordPress plugins and standalone PHP projects.
+
+### Components
+
+| Component | What it does | Live docs |
+| --- | --- | --- |
+| [HTML](components/HTML/README.md) | Stream-modify real-world HTML without `libxml2` (mirrors `WP_HTML_Tag_Processor` / `WP_HTML_Processor`). | [reference/html](https://wordpress.github.io/php-toolkit/reference/html.html) |
+| [XML](components/XML/README.md) | Stream-parse XML files on any PHP installation — no `libxml2` required. | [reference/xml](https://wordpress.github.io/php-toolkit/reference/xml.html) |
+| [Zip](components/Zip/README.md) | Stream-read and stream-write ZIP archives with no `libzip` dependency. | [reference/zip](https://wordpress.github.io/php-toolkit/reference/zip.html) |
+| [Markdown](components/Markdown/README.md) | Convert between Markdown and WordPress block markup. | [reference/markdown](https://wordpress.github.io/php-toolkit/reference/markdown.html) |
+| [BlockParser](components/BlockParser/README.md) | Parse and serialize WordPress block markup. | [reference/blockparser](https://wordpress.github.io/php-toolkit/reference/blockparser.html) |
+| [HttpClient](components/HttpClient/README.md) | Streaming, non-blocking, concurrent HTTP client — no `curl` extension. | [reference/httpclient](https://wordpress.github.io/php-toolkit/reference/httpclient.html) |
+| [HttpServer](components/HttpServer/README.md) | Minimal pure-PHP HTTP server primitives. | [reference/httpserver](https://wordpress.github.io/php-toolkit/reference/httpserver.html) |
+| [CORSProxy](components/CORSProxy/README.md) | A small CORS proxy for arbitrary HTTP traffic. | [reference/corsproxy](https://wordpress.github.io/php-toolkit/reference/corsproxy.html) |
+| [Git](components/Git/README.md) | Pure-PHP Git client and server. | [reference/git](https://wordpress.github.io/php-toolkit/reference/git.html) |
+| [Filesystem](components/Filesystem/README.md) | Single API across local files, ZIP, Git, in-memory, etc. | [reference/filesystem](https://wordpress.github.io/php-toolkit/reference/filesystem.html) |
+| [ByteStream](components/ByteStream/README.md) | Composable byte streaming utilities — readers, writers, filters. | [reference/bytestream](https://wordpress.github.io/php-toolkit/reference/bytestream.html) |
+| [DataLiberation](components/DataLiberation/README.md) | Streaming data importers for WordPress (WXR, zipped Markdown, remote git, URL rewriting…). | [reference/dataliberation](https://wordpress.github.io/php-toolkit/reference/dataliberation.html) |
+| [Encoding](components/Encoding/README.md) | Encoding-detection and conversion helpers. | [reference/encoding](https://wordpress.github.io/php-toolkit/reference/encoding.html) |
+| [Merge](components/Merge/README.md) | Three-way text and structural merge primitives. | [reference/merge](https://wordpress.github.io/php-toolkit/reference/merge.html) |
+| [Polyfill](components/Polyfill/README.md) | PHP 8.0 string functions and minimal WordPress stubs (hooks, escaping, `WP_Error`). | [reference/polyfill](https://wordpress.github.io/php-toolkit/reference/polyfill.html) |
+| [CLI](components/CLI/README.md) | Helpers for building friendly PHP command-line tools. | [reference/cli](https://wordpress.github.io/php-toolkit/reference/cli.html) |
+| [Blueprints](components/Blueprints/README.md) | Reproducible WordPress environment setup (the runtime behind `blueprints.phar`). | [reference/blueprints](https://wordpress.github.io/php-toolkit/reference/blueprints.html) |
+| [ToolkitCodingStandards](components/ToolkitCodingStandards/README.md) | Shared PHPCS ruleset used across the toolkit. | [reference/coding-standards](https://wordpress.github.io/php-toolkit/reference/coding-standards.html) |
+
+> **Looking for code samples?** Prefer the [live docs](https://wordpress.github.io/php-toolkit/) — every snippet there is executable in-browser and is verified against `trunk` in CI on every PR.
 
 ### Using the Blueprints v2 runner
 
@@ -30,17 +49,17 @@ how the runner is implemented.
 
 ### Using the components
 
-The individual components are now distributed via Composer at [https://packagist.org/packages/wp-php-toolkit](https://packagist.org/packages/wp-php-toolkit). You can install specific components you need rather than the entire toolkit.
-
-To install a specific component, use composer:
+Each component is independently published on Packagist under [`wp-php-toolkit/*`](https://packagist.org/packages/wp-php-toolkit/). Install only the pieces you need:
 
 ```bash
 composer require wp-php-toolkit/http-client
 composer require wp-php-toolkit/data-liberation
 composer require wp-php-toolkit/git
-# ... and so on for other components
+# ...
 ```
 
+Each Packagist page links back to its component's reference page so you can browse runnable examples without leaving the package listing.
+
 #### PHAR distribution
 
 For convenience, a standalone Blueprints runner and other tools from this repository are shipped as phar files available in the [GitHub releases](https://github.com/WordPress/php-toolkit/releases).
@@ -112,17 +131,16 @@ To fix the linting errors, run:
 composer lint-fix
 ```
 
-#### Composer
+#### Building the docs site
 
-The root composer.json file is an amalgamation of composer.base.json all
-component composer.json files. To regenerate it, run:
+The docs site under `docs/` is generated from `bin/_docs_components/<slug>.md`. To rebuild and preview locally:
 
 ```sh
-bin/regenerate_composer.json.php
+bash bin/build-docs-bundle.sh    # bundles toolkit + regenerates HTML
+python3 bin/serve-docs.py        # opens http://localhost:8787
 ```
 
-This will merge all the package-specific dependencies and the autoload rules into
-the root composer.json file.
+Snippets in the markdown sources run in CI on every PR (see `.github/workflows/snippet-tests.yml`) and in WordPress Playground from the live site.
 
 ### Windows compatibility
 

diff --git a/components/BlockParser/README.md b/components/BlockParser/README.md
@@ -1,5 +1,10 @@
 # BlockParser
 
+<!-- docs-site-banner -->
+> 📚 **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/blockparser.html](https://wordpress.github.io/php-toolkit/reference/blockparser.html)
+> Open the page to edit each snippet in your browser and run it in WordPress Playground.
+<!-- /docs-site-banner -->
+
 ## Why this exists
 
 WordPress stores post content as annotated HTML. Instead of inventing a separate file format, it embeds block boundaries directly inside HTML comments:

diff --git a/components/BlockParser/composer.json b/components/BlockParser/composer.json
@@ -3,9 +3,11 @@
     "description": "BlockParser component for WordPress.",
     "type": "library",
     "license": "GPL-2.0-or-later",
-    "require": {
-        "php": ">=7.2"
-    },
+    "keywords": [
+        "wordpress",
+        "php-toolkit"
+    ],
+    "homepage": "https://wordpress.github.io/php-toolkit/reference/blockparser.html",
     "authors": [
         {
             "name": "Adam Zielinski",
@@ -16,15 +18,23 @@
             "email": "wordpress@wordpress.org"
         }
     ],
+    "support": {
+        "issues": "https://github.com/WordPress/php-toolkit/issues",
+        "source": "https://github.com/WordPress/php-toolkit",
+        "docs": "https://wordpress.github.io/php-toolkit/reference/blockparser.html"
+    },
+    "require": {
+        "php": ">=7.2"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.5"
+    },
     "autoload": {
         "classmap": [
             "."
         ],
         "exclude-from-classmap": [
             "/Tests/"
         ]
-    },
-    "require-dev": {
-        "phpunit/phpunit": "^9.5"
     }
 }
diff --git a/components/Blueprints/README.md b/components/Blueprints/README.md
@@ -1,5 +1,10 @@
 # Blueprints
 
+<!-- docs-site-banner -->
+> 📚 **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/blueprints.html](https://wordpress.github.io/php-toolkit/reference/blueprints.html)
+> Open the page to edit each snippet in your browser and run it in WordPress Playground.
+<!-- /docs-site-banner -->
+
 Declarative WordPress site provisioning. Define a site's desired state as a JSON blueprint -- which plugins to install, which options to set, which content to import -- and let the runner execute it. Blueprints can create a new WordPress site from scratch or modify an existing one, making them useful for development environments, demo sites, automated testing, and reproducible WordPress setups.
 
 ## Installation

diff --git a/components/Blueprints/composer.json b/components/Blueprints/composer.json
@@ -3,6 +3,11 @@
     "description": "Blueprints component for WordPress.",
     "type": "library",
     "license": "GPL-2.0-or-later",
+    "keywords": [
+        "wordpress",
+        "php-toolkit"
+    ],
+    "homepage": "https://wordpress.github.io/php-toolkit/reference/blueprints.html",
     "authors": [
         {
             "name": "Adam Zielinski",
@@ -13,6 +18,11 @@
             "email": "wordpress@wordpress.org"
         }
     ],
+    "support": {
+        "issues": "https://github.com/WordPress/php-toolkit/issues",
+        "source": "https://github.com/WordPress/php-toolkit",
+        "docs": "https://wordpress.github.io/php-toolkit/reference/blueprints.html"
+    },
     "require": {
         "php": ">=7.2",
         "wp-php-toolkit/bytestream": "^0.8",

diff --git a/components/ByteStream/README.md b/components/ByteStream/README.md
@@ -1,5 +1,10 @@
 # ByteStream
 
+<!-- docs-site-banner -->
+> 📚 **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/bytestream.html](https://wordpress.github.io/php-toolkit/reference/bytestream.html)
+> Open the page to edit each snippet in your browser and run it in WordPress Playground.
+<!-- /docs-site-banner -->
+
 Composable streaming primitives for reading, writing, and transforming byte data in pure PHP. ByteStream provides a pull-based model where you request bytes from a source, peek at or consume them, and optionally transform them through filters like compression or checksums -- all without loading entire files into memory.
 
 ## Installation

diff --git a/components/ByteStream/composer.json b/components/ByteStream/composer.json
@@ -3,6 +3,11 @@
     "description": "ByteStream component for WordPress.",
     "type": "library",
     "license": "GPL-2.0-or-later",
+    "keywords": [
+        "wordpress",
+        "php-toolkit"
+    ],
+    "homepage": "https://wordpress.github.io/php-toolkit/reference/bytestream.html",
     "authors": [
         {
             "name": "Adam Zielinski",
@@ -13,18 +18,23 @@
             "email": "wordpress@wordpress.org"
         }
     ],
+    "support": {
+        "issues": "https://github.com/WordPress/php-toolkit/issues",
+        "source": "https://github.com/WordPress/php-toolkit",
+        "docs": "https://wordpress.github.io/php-toolkit/reference/bytestream.html"
+    },
     "require": {
         "php": ">=7.2"
     },
+    "require-dev": {
+        "phpunit/phpunit": "^9.5"
+    },
     "autoload": {
         "classmap": [
             "./"
         ],
         "exclude-from-classmap": [
             "/Tests/"
         ]
-    },
-    "require-dev": {
-        "phpunit/phpunit": "^9.5"
     }
 }
diff --git a/components/CLI/README.md b/components/CLI/README.md
@@ -1,5 +1,10 @@
 # CLI
 
+<!-- docs-site-banner -->
+> 📚 **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/cli.html](https://wordpress.github.io/php-toolkit/reference/cli.html)
+> Open the page to edit each snippet in your browser and run it in WordPress Playground.
+<!-- /docs-site-banner -->
+
 A POSIX-style command-line argument parser for PHP. It handles long options (`--verbose`), short options (`-v`), bundled short options (`-abc`), inline values (`--port=8080`, `-p=8080`), and positional arguments -- all in a single static method call with no external dependencies.
 
 ## Installation

diff --git a/components/CLI/composer.json b/components/CLI/composer.json
@@ -3,6 +3,11 @@
     "description": "CLI component for WordPress.",
     "type": "library",
     "license": "GPL-2.0-or-later",
+    "keywords": [
+        "wordpress",
+        "php-toolkit"
+    ],
+    "homepage": "https://wordpress.github.io/php-toolkit/reference/cli.html",
     "authors": [
         {
             "name": "Adam Zielinski",
@@ -13,6 +18,11 @@
             "email": "wordpress@wordpress.org"
         }
     ],
+    "support": {
+        "issues": "https://github.com/WordPress/php-toolkit/issues",
+        "source": "https://github.com/WordPress/php-toolkit",
+        "docs": "https://wordpress.github.io/php-toolkit/reference/cli.html"
+    },
     "require": {
         "php": ">=7.2"
     },

diff --git a/components/CORSProxy/README.md b/components/CORSProxy/README.md
@@ -1,5 +1,10 @@
 # CORSProxy
 
+<!-- docs-site-banner -->
+> 📚 **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/corsproxy.html](https://wordpress.github.io/php-toolkit/reference/corsproxy.html)
+> Open the page to edit each snippet in your browser and run it in WordPress Playground.
+<!-- /docs-site-banner -->
+
 A PHP CORS proxy that lets browser-based JavaScript make cross-origin requests to external services. Built for WordPress Playground to bridge `fetch()` calls to git servers and other APIs that don't set CORS headers. The proxy streams data bidirectionally, blocks requests to private IP ranges, filters sensitive headers, and enforces size limits -- all without external dependencies.
 
 ## Installation

diff --git a/components/CORSProxy/composer.json b/components/CORSProxy/composer.json
@@ -3,6 +3,11 @@
     "description": "CORSProxy component for WordPress.",
     "type": "library",
     "license": "GPL-2.0-or-later",
+    "keywords": [
+        "wordpress",
+        "php-toolkit"
+    ],
+    "homepage": "https://wordpress.github.io/php-toolkit/reference/corsproxy.html",
     "authors": [
         {
             "name": "Adam Zielinski",
@@ -13,18 +18,23 @@
             "email": "wordpress@wordpress.org"
         }
     ],
+    "support": {
+        "issues": "https://github.com/WordPress/php-toolkit/issues",
+        "source": "https://github.com/WordPress/php-toolkit",
+        "docs": "https://wordpress.github.io/php-toolkit/reference/corsproxy.html"
+    },
     "require": {
         "php": ">=7.2"
     },
+    "require-dev": {
+        "phpunit/phpunit": "^9.5"
+    },
     "autoload": {
         "psr-4": {
             "WordPress\\CORSProxy\\": ""
         },
         "exclude-from-classmap": [
             "/Tests/"
         ]
-    },
-    "require-dev": {
-        "phpunit/phpunit": "^9.5"
     }
 }
diff --git a/components/DataLiberation/README.md b/components/DataLiberation/README.md
@@ -1,5 +1,10 @@
 # DataLiberation
 
+<!-- docs-site-banner -->
+> 📚 **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/dataliberation.html](https://wordpress.github.io/php-toolkit/reference/dataliberation.html)
+> Open the page to edit each snippet in your browser and run it in WordPress Playground.
+<!-- /docs-site-banner -->
+
 Streaming data import and export for WordPress. Reads and writes WordPress content in multiple formats -- WXR (WordPress eXtended RSS), SQL dumps, block markup, and more -- without loading everything into memory. Designed for migrating content between WordPress sites, converting between formats, and processing large exports that would otherwise exhaust PHP's memory limits.
 
 ## Installation

diff --git a/components/DataLiberation/composer.json b/components/DataLiberation/composer.json
@@ -3,6 +3,11 @@
     "description": "Data Liberation component for WordPress.",
     "type": "library",
     "license": "GPL-2.0-or-later",
+    "keywords": [
+        "wordpress",
+        "php-toolkit"
+    ],
+    "homepage": "https://wordpress.github.io/php-toolkit/reference/dataliberation.html",
     "authors": [
         {
             "name": "Adam Zielinski",
@@ -13,6 +18,11 @@
             "email": "wordpress@wordpress.org"
         }
     ],
+    "support": {
+        "issues": "https://github.com/WordPress/php-toolkit/issues",
+        "source": "https://github.com/WordPress/php-toolkit",
+        "docs": "https://wordpress.github.io/php-toolkit/reference/dataliberation.html"
+    },
     "require": {
         "php": ">=7.2",
         "wp-php-toolkit/bytestream": "^0.8",

diff --git a/components/Encoding/README.md b/components/Encoding/README.md
@@ -1,5 +1,10 @@
 # Encoding
 
+<!-- docs-site-banner -->
+> 📚 **Runnable examples:** [https://wordpress.github.io/php-toolkit/reference/encoding.html](https://wordpress.github.io/php-toolkit/reference/encoding.html)
+> Open the page to edit each snippet in your browser and run it in WordPress Playground.
+<!-- /docs-site-banner -->
+
 Pure PHP utilities for UTF-8 validation, scrubbing, and conversion. This component detects invalid byte sequences, replaces them with the Unicode Replacement Character using the maximal subpart algorithm, and provides low-level tools for working with Unicode code points -- all without requiring the `mbstring` extension. When `mbstring` is available, the library delegates to it for better performance.
 
 ## Installation

diff --git a/components/Encoding/composer.json b/components/Encoding/composer.json
@@ -3,6 +3,11 @@
     "description": "Encoding component for WordPress.",
     "type": "library",
     "license": "GPL-2.0-or-later",
+    "keywords": [
+        "wordpress",
+        "php-toolkit"
+    ],
+    "homepage": "https://wordpress.github.io/php-toolkit/reference/encoding.html",
     "authors": [
         {
             "name": "Adam Zielinski",
@@ -13,6 +18,11 @@
             "email": "wordpress@wordpress.org"
         }
     ],
+    "support": {
+        "issues": "https://github.com/WordPress/php-toolkit/issues",
+        "source": "https://github.com/WordPress/php-toolkit",
+        "docs": "https://wordpress.github.io/php-toolkit/reference/encoding.html"
+    },
     "require": {
         "php": ">=7.2"
     },