I have spent over a decade in the WooCommerce REST API docs, and the old 4.2MB Slate page was rough. Try loading that single-page monster on a bad coffee shop connection while you are chasing a race condition in a checkout flow. So when the documentation moved to a new home, the interesting part was not the visual refresh.
Why the old documentation was failing us
For years the WooCommerce documentation lived on a standalone site. It covered everything, and it had two problems. The 4.2MB payload was the obvious one: every endpoint, parameter and example sat in a single file. The other was Slate, the framework behind it, which had effectively been abandoned, so keeping the site running turned into technical debt for the Woo team.
How we work has changed a lot in the meantime. I wrote earlier about WooCommerce REST API caching and the performance it buys, and the docs are held to the same standard. Slow docs cost you time on every lookup.
Why individual endpoint files matter for AI tools
The practical reason for the move is AI tooling. Cursor, Claude Code and GitHub Copilot all pull external documentation when they write integration code. Against the old WooCommerce REST API docs, an agent had to swallow megabytes of HTML and CSS to locate one endpoint, which burned the context window and the token budget with it.
The new structure at developer.woocommerce.com splits the documentation into one file per endpoint. Ask about the Products endpoint and the assistant fetches only the Products page, which comes back faster and with fewer wrong answers.
Raw markdown and the “Accept” header
The part I like most is the raw markdown. Append .md to any URL, or send the matching header, and you get clean unformatted text back. If you maintain a CLI tool or an internal documentation scraper, that removes a whole parsing layer.
<?php
/**
* Example: Fetching raw markdown for the Products endpoint
*/
$url = 'https://developer.woocommerce.com/docs/apis/rest-api/products.md';
$response = wp_remote_get( $url, [
'headers' => [
'Accept' => 'text/markdown',
],
] );
if ( ! is_wp_error( $response ) ) {
$markdown_content = wp_remote_retrieve_body( $response );
// Use this to feed an AI prompt or internal tool
error_log( $markdown_content );
}
Integration with the monorepo
Code changes and doc changes used to travel separately. The docs now live in the WooCommerce monorepo, so a pull request that adds a feature can carry its documentation in the same PR. That cuts the documentation lag everyone has hit after a big core release. It fits with the other developer-facing work in WooCommerce 10.7 and its new APIs.
If the WooCommerce REST API docs are eating your dev hours, I can take that work on. I have been building on WordPress since the 4.x days.
What changes for you day to day
Not much on the surface. Redirects are in place, so old bookmarks still land somewhere useful. The new sidebar and search are worth a look, though, since both beat scrolling through one enormous page. Legacy documentation stays up for older versions, but the new site is where daily work should point. It loads quickly, and it is finally shaped for the way developers and their tools actually read docs.
