MDX

One of Codespark's design goals is to build better documentation systems by adding interactive live preview components that enhance the reading experience. MDX is an essential tool for building documentation systems, allowing you to use JSX syntax to render components within Markdown files.

Codespark provides a remark plugin to extend MDX capabilities, enabling you to render Codespark components through code block directives.

Installation

npm install @codespark/plugin-remark

Vite

For Vite users, first install the official MDX Rollup plugin:

npm install @mdx-js/rollup

import remarkCodespark from '@codespark/plugin-remark';
import mdx from '@mdx-js/rollup'
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    mdx({ 
      providerImportSource: '@codespark/react', 
      remarkPlugins: [remarkCodespark] 
    })
  ]
});

Next.js

For Next.js users, first install the official MDX package:

npm install @next/mdx @mdx-js/loader @mdx-js/react

Then configure next.config.mjs to use the remark plugin:

import remarkCodespark from '@codespark/plugin-remark';
import createMDX from '@next/mdx';

const withMDX = createMDX({
  options: {
    remarkPlugins: [remarkCodespark], 
  },
});

/** @type {import('next').NextConfig} */
const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
};

export default withMDX(nextConfig);

Fumadocs

Fumadocs is a React.js documentation framework built on MDX. To use Codespark with Fumadocs, add the following configuration:

import { defineConfig } from 'fumadocs-mdx/config';
import remarkCodespark from '@codespark/plugin-remark';

export default defineConfig({
  mdxOptions: {
    providerImportSource: '@codespark/react', 
    remarkPlugins: [remarkCodespark] 
  }
})

Usage

Once configured, you can add directives to code blocks in MDX files to render different Codespark components.

codespark

Renders the code within a Codespark component, providing both editing and preview capabilities.

``` tsx codespark
export default function App() {
  return (
    <div className="text-center">
      <h1 className="text-xl font-bold">Hello World</h1>
      <p>This is my first Codes Park!</p>
    </div>
  );
}
```

codespark-editor

Renders the code within a CodesparkEditor component, providing editing functionality only.

```tsx codespark-editor
import { CodesparkEditor } from '@codespark/react';

export default function App() {
  return <CodesparkEditor />;
}
```

codespark-preview

Renders the code within a CodesparkPreview component, providing preview functionality only.

```tsx codespark-preview height=120
import dayjs from 'dayjs';
import { useEffect, useState } from 'react';

export default function App() {
  const [time, setTime] = useState(dayjs());

  useEffect(() => {
    const timer = setInterval(() => setTime(dayjs()), 1000);
    return () => clearInterval(timer);
  }, []);

  return (
    <div className="flex items-center justify-center gap-6 p-4">
      <div className="text-center">
        <p className="text-3xl font-bold tabular-nums">{time.format('HH:mm:ss')}</p>
        <p className="text-sm text-gray-500">{time.format('YYYY-MM-DD')}</p>
      </div>
    </div>
  );
}
```

Props

Code block directives support passing string-type and boolean-type props to the corresponding components, such as height and width. For more details, see the API reference and Remark Plugin documentation.

```tsx codespark-preview height=120
// ...
```