@uiw/react-markdown-preview-example
Version:
Preview the markdown files and run the React examples in the documentation.
276 lines (227 loc) ā¢ 10.1 kB
Markdown
<!--rehype:ignore:start-->
/react-markdown-preview-example
===
<!--rehype:ignore:end-->
[](https://jaywcjlove.github.io/#/sponsor)
[](https://github.com/uiwjs/react-markdown-preview-example/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@uiw/react-markdown-preview-example)
[](https://www.npmjs.com/package/@uiw/react-markdown-preview-example)
[](https://github.com/facebook/react/releases)
Preview the markdown files and run the React examples in the documentation.
## Features
š Use Typescript to write, better code hints.
š Support dark/light mode
šš¾āāļø Support [GFM](https://github.github.com/gfm/) (autolink literals, footnotes, strikethrough, tables, tasklists).
š Support for defining styles via comment.
šš¼āāļø GitHub style: The markdown content is rendered as close to the way it's rendered on GitHub as possible.
## Quick Start
```bash
$ npm install /react-markdown-preview-example --save
```
```jsx
import MarkdownPreviewExample from '/react-markdown-preview-example';
import data from './docs/README.md';
data.source // => `README.md` raw string text
data.components // => The component index object, the React component converted from the markdown indexed example. (need to configure meta)
data.data // => The component source code index object, the sample source code indexed from markdown. (need to configure meta)
const Github = MarkdownPreviewExample.Github;
const Example = MarkdownPreviewExample.Example;
const NavMenu = MarkdownPreviewExample.NavMenu;
<MarkdownPreviewExample
source={data.source}
components={data.components}
data={data.data}
title="MarkdownPreviewExample for React"
version={`v${VERSION}`}
>
<Github href="https://github.com/uiwjs/react-markdown-preview-example" />
<Example>
<div>test</div>
</Example>
</MarkdownPreviewExample>
```
```jsx
import PreviewExample from '/react-markdown-preview-example';
<PreviewExample.NavMenu
title="Markdown Preview Example"
menus={[
<a target="_blank" href="https://uiwjs.github.io/react-markdown-preview/" rel="noopener noreferrer">Markdown</a>,
<a target="_blank" href="https://jaywcjlove.github.io/#/sponsor" rel="noopener noreferrer">Sponsor</a>
]}
/>
```
just markdown _preview_ and **run** in markdown show **react** example.
```tsx
import MarkdownPreview from '/react-markdown-preview-example/markdown';
import data from './docs/README.md';
data.source // => `README.md` raw string text
data.components // => The component index object, the React component converted from the markdown indexed example. (need to configure meta)
data.data // => The component source code index object, the sample source code indexed from markdown. (need to configure meta)
<Markdown source={data.source} data={data} />
```
```ts
import type { MarkdownPreviewProps } from '/react-markdown-preview';
import type { CodeBlockData } from 'markdown-react-code-preview-loader';
export interface MarkdownProps extends MarkdownPreviewProps {
data: CodeBlockData;
}
export default function Markdown(props: MarkdownProps): import("react/jsx-runtime").JSX.Element;
```
There is a step to pay attention to, which needs to configure the webpack [`loader`](https://www.npmjs.com/package/markdown-react-code-preview-loader). The configuration and usage methods are consistent in Webpack:
```ts
// .kktrc.ts
import webpack, { Configuration } from 'webpack';
import scopePluginOptions from '/scope-plugin-options';
import { LoaderConfOptions } from 'kkt';
export default (conf: Configuration, env: 'development' | 'production', options: LoaderConfOptions) => {
// ....
config.module.rules.forEach((ruleItem) => {
if (typeof ruleItem === 'object') {
if (ruleItem.oneOf) {
ruleItem.oneOf.unshift({
test: /.md$/,
use: [
{
loader: 'markdown-react-code-preview-loader',
options: { lang:["jsx","tsx"] },
},
],
});
}
}
});
// ....
return conf;
};
```
Or
```ts
// .kktrc.ts
import scopePluginOptions from '/scope-plugin-options';
import { LoaderConfOptions, WebpackConfiguration } from 'kkt';
import { mdCodeModulesLoader } from 'markdown-react-code-preview-loader';
export default (conf: WebpackConfiguration, env: 'development' | 'production', options: LoaderConfOptions) => {
// ....
conf = mdCodeModulesLoader(conf);
// ....
return conf;
};
```
`src/react-app-env.d.ts`
```ts
declare var VERSION: string;
declare module '*.md' {
import { CodeBlockData } from 'markdown-react-code-preview-loader';
const src: CodeBlockData;
export default src;
}
```
## Preview React Example
```tsx mdx:preview&boreder=0
import React from 'react';
const Demo = () => <div>Preview React Example</div>
export default Demo;
```
Note ā ļø: You need to add a special `meta` identifier to the code block example, and [`loader`](https://www.npmjs.com/package/markdown-react-code-preview-loader) will index the `react` example for code conversion.
```
Meta Tag Meta ID Meta Param
āāāāāāāā āāāāāāā āāāāāāāāāā
āāāāāāāāāāā²āāāāāāāāāāāāā±āāāāāāāā±āāāāāāāāāāāāāāāāāāāāāāāāāāā®
ā ```jsx mdx:preview:demo12&boreder=0 ā
ā import React from "react" ā
ā const Demo = () => <div>Preview React Example</div> ā
ā export default Demo ā
ā ``` ā
ā°āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāÆ
```
1. `mdx:` special identifier prefix
2. `mdx:preview` Controls whether to perform example indexing, and obtain the required example object through the corresponding line number.
3. `mdx:preview:demo12` Uniquely identified by `demo12`, accurately obtain the `example code` or `example component object` of the index.
4. `mdx:preview:&code=0&border=0` pass the parameters for the rendering layer to use.
Support **meta** param:
1. `title` sample title
2. `boreder` = `1` | `0`, Set the display border
3. `checkered` = `1` | `0`, disable Checkered
4. `code` = `1` | `0`, Whether to display source code
5. `toolbar` = `1` | `0`, Whether to show the code folding button
```tsx mdx:preview
import React from 'react';
const Demo = () => <div>Preview React Example: <b>mdx:preview</b></div>
export default Demo;
```
```tsx mdx:preview&checkered=0
import React from 'react';
const Demo = () => <div>Preview React Example: <b>mdx:preview&checkered=0</b></div>
export default Demo;
```
## Props
```ts
import '/dark-mode';
import type { PropsWithChildren } from 'react';
import type { CodeBlockData } from 'markdown-react-code-preview-loader';
import type { GitHubCornersProps } from '/react-github-corners';
import type { MarkdownPreviewProps } from '/react-markdown-preview';
declare function Github(props: GitHubCornersProps): null;
declare function Corners(props: GlobalStore['darkMode']): null;
declare function Example({ children }: PropsWithChildren): null;
declare function NavMenu(props: NavMenuProps): null;
export interface MarkdownPreviewExampleProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
source: string;
components: CodeBlockData['components'];
data: CodeBlockData['data'];
version?: string;
title?: JSX.Element | string;
markdownProps?: MarkdownPreviewProps;
exampleProps?: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>;
logo?: JSX.Element;
description?: JSX.Element | string;
disableCorners?: boolean;
disableDarkMode?: boolean;
disableHeader?: boolean;
disableBackToUp?: boolean;
}
declare const InternalMarkdownPreviewExample: import("react").ForwardRefExoticComponent<MarkdownPreviewExampleProps & import("react").RefAttributes<HTMLUListElement>>;
type ExampleComponent = typeof InternalMarkdownPreviewExample & {
Example: typeof Example;
Github: typeof Github;
Corners: typeof Corners;
NavMenu: typeof NavMenu;
};
declare const MarkdownPreviewExample: ExampleComponent;
export default MarkdownPreviewExample;
export interface NavMenuProps {
title?: string;
logo?: React.ReactNode;
github?: string;
menus?: Array<React.AnchorHTMLAttributes<HTMLAnchorElement>>;
}
export interface GlobalStore {
corners: GitHubCornersProps;
darkMode: Partial<HTMLElementTagNameMap['dark-mode']>;
example?: React.ReactNode;
navMenu?: NavMenuProps;
}
```
## Development
Runs the project in development mode.
```bash
# Step 1, run first, listen to the component compile and output the .js file
# listen for compilation output type .d.ts file
npm run watch
# Step 2, development mode, listen to compile preview website instance
npm run start
```
Builds the app for production to the build folder.
```bash
npm run build
```
The build is minified and the filenames include the hashes.
Your app is ready to be deployed!
## Contributors
As always, thanks to our amazing contributors!
<a href="https://github.com/uiwjs/react-markdown-preview-example/graphs/contributors">
<img src="https://uiwjs.github.io/react-markdown-preview-example/CONTRIBUTORS.svg" />
</a>
Made with [contributors](https://github.com/jaywcjlove/github-action-contributors).
## License
Licensed under the MIT License.