MDX React Docgen Typescript Remark Plugin

1.0.1 · active · verified Sun Apr 19

remark-mdx-react-docgen-typescript is a Remark plugin designed to integrate `react-docgen-typescript` functionality directly into MDX documents. It allows developers to automatically extract and display TypeScript React component documentation within their MDX content using a directive syntax (e.g., `::component-docs{file="./Component.tsx"}`). The plugin processes MDX files, identifies these directives, and replaces them with JSX `<ComponentDocs>` elements containing `propsData` derived from the specified React component files. The current stable version is 1.0.1. Its release cadence appears to be ad-hoc, with recent updates in late 2023. Key differentiators include its tight integration with the `unified` and `remark` ecosystems, specifically for MDX, and its ability to leverage `react-docgen-typescript` for type-aware documentation generation, making it suitable for monorepos or design systems that use TypeScript and MDX for documentation.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart demonstrates how to set up `remark-mdx-react-docgen-typescript` with `@mdx-js/mdx` to process an MDX file containing a `::component-docs` directive. It shows the necessary imports for `remark-directive` and the docgen plugin, then compiles the MDX, illustrating how component documentation is extracted and inserted as JSX props into a `<ComponentDocs>` component.

import { readFile } from 'node:fs/promises';
import { compile } from '@mdx-js/mdx';
import remarkDirective from 'remark-directive';
import remarkReactDocgen from 'remark-mdx-react-docgen-typescript';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Create a dummy Component.tsx for demonstration purposes
const componentCode = `
/**
 * A simple example component.
 * @param greeting The greeting message.
 */
export function MyComponent({ greeting }: { greeting: string }) {
  return <div>{greeting}, World!</div>;
};
`;

// In a real scenario, this would be a file on disk.
// For quickstart, we'll simulate the MDX and component content.
const mdxContent = `
# My Component Documentation

This is an example of documenting MyComponent:

::component-docs{file="./MyComponent.tsx" greeting="Hello from MDX"}
`;

// Simulate writing the component file (optional, for direct execution)
// In a real project, MyComponent.tsx would exist alongside your MDX.
// For this quickstart, we'll compile the MDX assuming MyComponent.tsx exists
// or is mocked during compilation.

// To run this, you'd typically have MyComponent.tsx in the same directory
// as your MDX file. For a self-contained example:
// await fs.promises.writeFile(path.join(__dirname, 'MyComponent.tsx'), componentCode);

async function compileMdxWithDocgen() {
  try {
    // Assuming 'MyComponent.tsx' is available where your MDX points.
    // For this example, we'll configure rootDir to point to __dirname
    // and ensure react-docgen-typescript can find the component.
    const { contents } = await compile(mdxContent, {
      jsx: true,
      remarkPlugins: [
        remarkDirective,
        [remarkReactDocgen, { rootDir: __dirname, reactDocGenOptions: { tsConfigPath: path.join(__dirname, 'tsconfig.json') } }]
      ],
    });
    console.log(contents);
  } catch (error) {
    console.error('MDX Compilation Error:', error);
  }
}

// A tsconfig.json is often required for react-docgen-typescript
// Example content for tsconfig.json:
// {"compilerOptions": {"jsx": "react", "module": "esnext", "target": "esnext", "esModuleInterop": true, "skipLibCheck": true}}
// Ensure it exists in __dirname for this example to work with a real file.

compileMdxWithDocgen();

view raw JSON →