Doc: Explore migrating to MDX #323
Description
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.
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