Doc: Explore migrating to MDX

[adamziel]

Reusing doc is a challenge, e.g. I'd like to embed plenty of Blueprint steps docs on the "Getting started" page. MDX seems to be tailored for that and it integrates with Docusaurus.

https://mdxjs.com/

My ideal use-case is to have the following TypeScript::

/**
 * The step to install a WordPress plugin in the Playground.
 *
 * @example
 *
 * <code>
 * {
 * 	    "step": "installPlugin",
 * 		"pluginZipFile": "http://example.com/plugin.zip",
 * 		"options": {
 * 			"activate": true
 * 		}
 * }
 * </code>
 */
export interface InstallPluginStep<ResourceType> {
	/**
	 * The step identifier.
	 */
	step: 'installPlugin';
	/**
	 * The plugin zip file to install.
	 */
	pluginZipFile: ResourceType;
	/**
	 * Optional installation options.
	 */
	options?: InstallPluginOptions;
}

export interface InstallPluginOptions {
	/**
	 * Whether to activate the plugin after installing it.
	 */
	activate?: boolean;
}

/**
 * Installs a WordPress plugin in the Playground.
 * Technically, it uses the same plugin upload form as a WordPress user
 * would, and then activates the plugin if needed.
 *
 * @param playground The playground client.
 * @param pluginZipFile The plugin zip file.
 * @param options Optional. Set `activate` to false if you don't want to activate the plugin.
 */
export const installPlugin: StepHandler<InstallPluginStep<File>> = async (
	playground,
	{ pluginZipFile, options = {} },
	progress?
)

And then reuse it in multiple documents like:

• Getting started with Blueprints
• Blueprints as JSON
• Blueprints as functions

# Getting started with Blueprints

... some content ...

You can install Gutenberg with the `installPlugin` step:

<LiveCodeSnippet>
   <BlueprintStepUsage step="installPlugin" />
</LiveCodeSnippet>

# Blueprints as JSON
... content...

### JSON steps

<BlueprintJSONStepsList />

# Blueprints as functions

... content...

### Functional Steps

<BlueprintFunctionsStepsList />

And get nicely formatted examples, live code snippets, and inline API docs in all three places. Furthermore, I want them to automatically reflect any changes in the code, e.g. newly committed Blueprint steps or any changes in the function signature.

Related: #217

[adamziel]

Mdx could provide testable, interactive docs if they came with:

• Code examples
• Initialization scripts
• Any fixtures required
• Expected output

WordPress/Documentation-Issue-Tracker#730 (comment)

We could even put snippets in docstrings if the module-level docstring shipped runtime details. E.g:

/**
 * Runtime: Playground
 * Execution Script:
 * Import { startPlaygroundWeb, runBlueprint } from …
 * const client = await startPlaygroundWeb(…)
 */

/**
 * @example
 * > await loginStep(client);
 * > client.username
 * admin
 */
export function loginStep(client, ) {
   // …
}

[adamziel]

Docusaurus seems incredibly well suited for what Playground needs:

Importing components

Live code snippets could be embedded directly in the docs – how cool is that?!

Importing code snippets

You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to Webpack raw-loader. In order to use raw-loader, you first need to install it in your project

import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';

<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>

Importing Markdown

You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages.

<span>Hello {props.name}</span>

This is text some content from `_markdown-partial-example.mdx`.

import PartialExample from './_markdown-partial-example.mdx';

<PartialExample name="Sebastien" />

[adamziel]

There's also support for:

• Tabs (e.g. JSON / Functional Blueprint examples)
• Interactive code editor – big YAY for JavaScript examples. I bet it could work with PHP and Interactivity API, too. CC @michalczaplinski
• Strongly validated Markdown links. Goodbye broken links.
• Mermaid Diagrams. Highly useful in a repo like this where a lot of concepts require visual aids.

There's even a plugin to grab Typedoc output

[adamziel]

This is done as of #398