https://github.com/rippling/remark-mdx-react-docgen-typescript
A mdx plugin to extract a react component documentation using react-docgen-typescript
https://github.com/rippling/remark-mdx-react-docgen-typescript
documentation mdx mdx-js react react-docgen-typescript remark unified
Last synced: 11 months ago
JSON representation
A mdx plugin to extract a react component documentation using react-docgen-typescript
- Host: GitHub
- URL: https://github.com/rippling/remark-mdx-react-docgen-typescript
- Owner: Rippling
- License: apache-2.0
- Created: 2024-01-28T05:01:51.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-14T14:57:52.000Z (almost 2 years ago)
- Last Synced: 2024-03-14T22:29:40.087Z (almost 2 years ago)
- Topics: documentation, mdx, mdx-js, react, react-docgen-typescript, remark, unified
- Language: TypeScript
- Homepage:
- Size: 129 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `remark-mdx-react-docgen-typescript`
📝 A mdx plugin to extract a react component documentation using `react-docgen-typescript`
[](https://badge.fury.io/js/remark-mdx-react-docgen-typescript)
## Installation
```sh
npm install -D remark-directive remark-mdx-react-docgen-typescript
```
## Setup
```js
import remarkReactDocgen from 'remark-mdx-react-docgen-typescript';
// or
// const remarkReactDocgen = require('remark-mdx-react-docgen-typescript').default;
```
See [**Using plugins**](https://github.com/remarkjs/remark/blob/master/doc/plugins.md#using-plugins) for more instructions in the official documentation.
## Usage
For example, given a file named example.mdx with the following contents:
```md
::component-docs{file="./Component.tsx"}
```
The following script:
```js
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';
const { contents } = await compile(await readFile('example.mdx'), {
jsx: true,
remarkPlugins: [remarkDirective, remarkReactDocgen],
});
console.log(contents);
```
Roughly yields:
```jsx
export default function MDXContent() {
return
}
```
You may use `@mdx-js/react` to define the component for `ComponentDocs` tag name:
```jsx
import { MDXProvider } from '@mdx-js/react';
import ComponentDocs from './ComponentDocs';
// ^-- Assumes an integration is used to compile MDX to JS, such as
// `@mdx-js/esbuild`, `@mdx-js/loader`, `@mdx-js/node-loader`, or
// `@mdx-js/rollup`, and that it is configured with
// `options.providerImportSource: '@mdx-js/react'`.
/** @type {import('mdx/types.js').MDXComponents} */
const components = {
ComponentDocs,
};
console.log(
);
```
The file path is relative to the markdown file path. You can use `` at the start of the path to import files relatively from the rootDir:
```md
::component-docs{file="/Component.tsx"}
```
You may also specify additional attributes that will be forwarded as props to ComponentDocs component:
```md
::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 `` refers to. Defaults to `process.cwd()`.
- `reactDocGenOptions: object`: Options for [`react-docgen-typescript`](https://github.com/styleguidist/react-docgen-typescript?tab=readme-ov-file#options).
## Testing
After installing dependencies with `npm install`, the tests can be run with: `npm test`
## License
Rippling People Center Inc.
[Apache 2.0](LICENSE)