remark-mdx-react-docgen-typescript

📝 A mdx plugin to extract a react component documentation using react-docgen-typescript

Installation

1npm install -D remark-directive remark-mdx-react-docgen-typescript

Setup

1import remarkReactDocgen from 'remark-mdx-react-docgen-typescript';
2// or
3// const remarkReactDocgen = require('remark-mdx-react-docgen-typescript').default;

See Using plugins for more instructions in the official documentation.

Usage

For example, given a file named example.mdx with the following contents:

1::component-docs{file="./Component.tsx"}

The following script:

1import { readFile } from 'node:fs/promises';
2
3import { compile } from '@mdx-js/mdx';
4import remarkDirective from 'remark-directive';
5import remarkReactDocgen from 'remark-mdx-react-docgen-typescript';
6
7const { contents } = await compile(await readFile('example.mdx'), {
8  jsx: true,
9  remarkPlugins: [remarkDirective, remarkReactDocgen],
10});
11console.log(contents);

Roughly yields:

1export default function MDXContent() {
2  return <ComponentDocs
3    propsData={[{
4      "tags": {},
5      "filePath": "${cwd}/__fixtures__/Component.tsx",
6      "description": "",
7      "displayName": "Component",
8      "methods": [],
9      "props": {...}
10      ...
11    }]}
12  />
13}

You may use @mdx-js/react to define the component for ComponentDocs tag name:

1import { MDXProvider } from '@mdx-js/react';
2import ComponentDocs from './ComponentDocs';
3// ^-- Assumes an integration is used to compile MDX to JS, such as
4// `@mdx-js/esbuild`, `@mdx-js/loader`, `@mdx-js/node-loader`, or
5// `@mdx-js/rollup`, and that it is configured with
6// `options.providerImportSource: '@mdx-js/react'`.
7
8/** @type {import('mdx/types.js').MDXComponents} */
9const components = {
10  ComponentDocs,
11};
12
13console.log(
14  <MDXProvider components={components}>
15    <Post />
16  </MDXProvider>
17);

The file path is relative to the markdown file path. You can use <rootDir> at the start of the path to import files relatively from the rootDir:

1::component-docs{file="<rootDir>/Component.tsx"}

You may also specify additional attributes that will be forwarded as props to ComponentDocs component:

1::component-docs{file="./Component.tsx" extraProp="value"}

Options

• componentName: string: The name of tag/component this plugin will use in JSX. Defaults to ComponentDocs.
• directiveName: string: The directive name. Defaults to component-docs.
• fileAttributeName: string: The attribute name for file path. Defaults to file.
• rootDir: string: Change what <rootDir> refers to. Defaults to process.cwd().
• reactDocGenOptions: object: Options for react-docgen-typescript.

Testing

After installing dependencies with npm install, the tests can be run with: npm test

License

Rippling People Center Inc. Apache 2.0