[Docs] Migrate WordPress Playground Documentation to WordPress.org Handbook

[fellyph]

Based on community feedback, we are migrating the official WordPress Playground documentation from its current Docusaurus setup to the standard Handbook format on WordPress.org. This transition will establish Playground as a core WordPress project and provide a more familiar documentation structure for our users.

To accomplish this efficiently, we are migrating essential components to alternatives that can be natively rendered by the Handbook scripts. This approach avoids duplicating markdown files and allows both the Docusaurus and Handbook versions to stay online during the transition.

Migration Roadmap & Progress

Phase 1: The English Migration

Our immediate priority is getting the core English documentation published in the Handbook. During this phase, both docs will be live. Once the migration is complete, the English version will redirect to the Handbook.

• Anchor Links & IDs: Remove hardcoded IDs used for internal page linking (the Handbook handles this natively). [Docs] Removing heading IDs to make docs compatible to migrate to org #3466
• Asset Loading: Update asset loading to point directly to raw files hosted on GitHub, ensuring images render correctly. [Docs] Load assets from githubusercontent to make it compatible with handbook #3467
• MDX Fragments: Adapt heavily utilized MDX fragments (reusable snippets) for an inline structure. (Currently in PR review) [Docs] Removing docs fragments #3470
• Callout Components: Create Handbook-compatible alternatives for Docusaurus components (Warnings, Info, Tips) so important context is still highlighted.
• replace info component [docs] Replacing info component by compatible handbook element #3496
• replace warn component
• replace tips component
• SEO & Open Graph Data: Verify Open Graph data (logos, descriptions, titles) and collaborate with the Handbook team to ensure they are dynamically parsed for SEO.

Phase 2: Internationalization (i18n)

Because Handbook support for translations is still evolving, the Docusaurus site will remain live strictly as a fallback for international users (over 220 translated pages).

• Define a set of pages eligible for translation and publishing in the new handbook.
• Establish fallback routing: Ensure the first "block" of introductory pages is translated at a minimum; otherwise, redirect the user to the English version.
• Lead contributor discussions for an ongoing i18n solution (scheduled for WordCamp Asia).

Phase 3: The “Ask AI” Feature

We need to carefully migrate the “Ask AI” button (powered by Kapa.ai) to the official .org domain.

• Testing: Coordinate with the Docs team regarding the proposal to test the Kapa.ai solution on the .org account.
• Privacy Considerations: Discuss privacy policies with the documentation team regarding how user queries are stored in the Kapa.ai dashboard before implementation.

References

• Announcement Post: Migrating WordPress Playground Documentation to WordPress.org