OpenParable
Skip to content
← Back to skills

Livecodes/markdown Integration

Apps & Automation
livecodes/markdown-integration

Livecodes/markdown Integration is an Agent Skill for apps & automation published in the live-codes/livecodes repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Integrate LiveCodes with documentation sites using remark-livecodes, markdown-it-livecodes, gatsby-remark-livecodes, or marked-livecodes for Docusaurus, Astro, VitePress, Next.js, and Storybook.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/live-codes/livecodes/blob/HEAD/.agents/skills/livecodes/markdown-integration/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/livecodes-markdown-integration, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

This skill requires sdk-embedding. Read it first for foundational concepts.

LiveCodes — Integrate with Documentation Sites

Convert Markdown/MDX code blocks to interactive LiveCodes playgrounds using plugins for popular documentation frameworks.

Setup

Docusaurus (remark-livecodes)

npm install -D remark-livecodes
// docusaurus.config.js
module.exports = {
  presets: [
    [
      'classic',
      {
        docs: {
          remarkPlugins: [
            [
              require('remark-livecodes'),
              {
                /* options */
              },
            ],
          ],
        },
      },
    ],
  ],
};

Astro (remark-livecodes)

npm install -D remark-livecodes
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkLivecodes from 'remark-livecodes';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [
      [
        remarkLivecodes,
        {
          /* options */
        },
      ],
    ],
  },
});

VitePress (markdown-it-livecodes)

npm install -D markdown-it-livecodes
// .vitepress/config.js
import { defineConfig } from 'vitepress';
import markdownItLivecodes from 'markdown-it-livecodes';

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(markdownItLivecodes, {
        /* options */
      });
    },
  },
});

Next.js (remark-livecodes)

npm install -D remark-livecodes
// next.config.js
import createMDX from '@next/mdx';
import remarkLivecodes from 'remark-livecodes';

const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
};

const withMDX = createMDX({
  options: {
    remarkPlugins: [
      [
        remarkLivecodes,
        {
          /* options */
        },
      ],
    ],
  },
});

export default withMDX(nextConfig);

react-markdown

npm install remark-livecodes
import Markdown from 'react-markdown';
import remarkLivecodes from 'remark-livecodes';

const markdown = '```jsx livecodes\nexport default () => <h1>Hello</h1>\n```';

<Markdown
  remarkPlugins={[
    [
      remarkLivecodes,
      {
        /* options */
      },
    ],
  ]}
>
  {markdown}
</Markdown>;

Storybook (remark-livecodes)

// storybook/main.js
import remarkLivecodes from 'remark-livecodes';

export default {
  addons: [
    {
      name: '@storybook/addon-docs',
      options: {
        mdxPluginOptions: {
          mdxCompileOptions: {
            remarkPlugins: [
              [
                remarkLivecodes,
                {
                  /* options */
                },
              ],
            ],
          },
        },
      },
    },
  ],
};

Gatsby (gatsby-remark-livecodes)

npm install -D gatsby-remark-livecodes
// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-transformer-remark',
      options: {
        plugins: [
          {
            resolve: 'gatsby-remark-livecodes',
            options: {
              /* options */
            },
          },
        ],
      },
    },
  ],
};

Usage

Basic code block → Playground

```jsx livecodes
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount((c) => c + 1)}>{count}</button>;
}

export default App;
```

Add livecodes to the code block language to render as an interactive playground.

Button or Link instead of embed

```jsx livecodes render=button
console.log('Edit in LiveCodes');
```
```jsx livecodes render=link
console.log('Edit in LiveCodes');
```
renderBehavior
playground (default)Embed playground in page
buttonShow code block + "Edit in LiveCodes" button
linkShow code block + "Edit in LiveCodes" link
metaAdd URL to data-livecodes-url attribute

Options

Configure plugin options to apply to all code blocks:

remarkPlugins: [
  [remarkLivecodes, {
    // Embed options
    loading: 'lazy',
    params: { console: 'open' },

    // Plugin options
    render: 'playground',  // 'playground' | 'button' | 'link' | 'meta'
    height: '400px',
    className: 'my-playground',
    auto: false,  // Auto-enable for all code blocks
  }],
],

Meta Parameters

Configure individual code blocks with meta parameters:

```jsx livecodes height=500px console=open theme=light
console.log('Hello World');
```
ParameterDescription
livecodesEnable playground rendering
renderRender mode: playground, button, link, meta
heightIframe height
classNameCSS class for iframe/button/link
langOverride language
<param>Any LiveCodes query parameter (e.g., console=open, theme=light)

Common Meta Parameters

```jsx livecodes render=button
// Button opens in LiveCodes
```

```py livecodes lang=py-wasm console=open
# Force Python (Wasm) language
print("Hello from Python")
```

```typescript livecodes theme=light editor=monaco
// Light theme, Monaco editor
const x: number = 1;
```

Common Mistakes

MEDIUM Not installing peer dependencies

# Each plugin requires its host library
npm install remark remark-livecodes     # remark-livecodes
npm install marked marked-livecodes     # marked-livecodes
npm install markdown-it markdown-it-livecodes  # markdown-it-livecodes
npm install gatsby-plugin-remark gatsby-remark-livecodes  # Gatsby

Install the host library alongside the LiveCodes plugin. Each plugin wraps a specific Markdown processor.

Source: docs/docs/markdown-to-livecodes.mdx — Installation sections

LOW Forgetting livecodes parameter in code block

```jsx
// This is just a static code block (no livecodes parameter)
export default () => <h1>Hello</h1>;
```

```jsx livecodes
// This becomes an interactive playground
export default () => <h1>Hello</h1>;
```

Without the livecodes parameter, the code block renders as static Markdown. Add it to enable the playground.

Set auto: true in options to convert all code blocks automatically.

Source: docs/docs/markdown-to-livecodes.mdx — Meta Parameters section

Plugin Packages

PackageUse WithInstall
remark-livecodesDocusaurus, Astro, Next.js, Storybook, react-markdownnpm install -D remark-livecodes
markdown-it-livecodesVitePress, Eleventynpm install -D markdown-it-livecodes
marked-livecodesMarkednpm install -D marked-livecodes
gatsby-remark-livecodesGatsbynpm install -D gatsby-remark-livecodes