Designed to works with MDX files, Playground is a remark plugin that can be used in many React frameworks, like Next, Remix, Astro, and Gatsby. With just one step configuration you can use Playground to provide super powers for your components examples, and docs.

Playground enables you to create interactive and engaging examples of your components that can be easily customized and shared with others. The plugin supports live code editing and rendering, allowing you to quickly and easily experiment with different configurations and settings for your components.

Quick Setup

To get started with Playground, you can install it using your preferred package manager:

npm install remark-playground --save

To use Playground with a specific React framework, you'll need to configure remark within that framework. Here's how to set it up with some popular frameworks:

Next.js

To use Playground with Next.js, you'll need to add a next.config.mjs file to the root of your project with the following content:

const withMDX = require("@next/mdx")({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [require("remark-playground/plugin")],
  },
});
 
module.exports = withMDX();

This will configure Next.js to use Playground with MDX files in your project.

Remix

To use Playground with Remix, you'll need to add a mix.config.js file to the root of your project with the following content:

const mixMDX = require("@remix-run/mdx");
const remarkPlugins = [require("remark-playground/plugin")];
 
module.exports = mixMDX.default({
  remarkPlugins,
});

This will configure Remix to use Playground with MDX files in your project.

Astro

To use Playground with Astro, you'll need to add a astro.config.mjs file to the root of your project with the following content:

import { createPlugin } from "astro";
import remark from "remark";
import remarkPrism from "@mapbox/remark-prism";
import playground from "remark-playground/plugin";
 
export default {
  plugins: [
    createPlugin({
      name: "remark",
      plugins: [playground, [remarkPrism, { ignoreMissing: true }], remark()],
    }),
  ],
};

This will configure Astro to use Playground with MDX files in your project.

Gatsby

To use Playground with Gatsby, you'll need to add a gatsby-config.js file to the root of your project with the following content:

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-mdx",
      options: {
        gatsbyRemarkPlugins: [
          {
            resolve: "gatsby-remark-vscode",
            options: {
              theme: "Dark+ (default dark)",
              extensions: ["theme-darcula"],
              inlineCode: {
                marker: ">",
              },
            },
          },
        ],
        remarkPlugins: [require("remark-slug")],
        remarkPlugins: [require("remark-playground/plugin")],
      },
    },
  ],
};

This will configure Gatsby to use Playground with MDX files in your project.

Usage

Once you have set up Playground, you can begin using it to create examples and documentation for your components. You can customize the appearance and behavior of your examples using a wide range of settings and options, including CSS, JavaScript, and HTML.

For example, you can use the Playground component to create an interactive example of a button component:

import Playground from 'remark-playground';
 
import Button '...'
 
# Button
 
The `Button` component is a simple button that can be used in your application.
 
<Playground>
  <Button>Click me</Button>
</Playground>

This will render an interactive example of the Button component that users can play with and customize. You can also use Playground to create more complex examples and documentation, depending on your needs.