@uiw/react-markdown-preview-example

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 (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

1$ npm install @uiw/react-markdown-preview-example --save

1import MarkdownPreviewExample from '@uiw/react-markdown-preview-example';
2import data from './docs/README.md';
3
4data.source     // => `README.md` raw string text
5data.components // => The component index object, the React component converted from the markdown indexed example. (need to configure meta)
6data.data       // => The component source code index object, the sample source code indexed from markdown. (need to configure meta)
7
8const Github = MarkdownPreviewExample.Github;
9const Example = MarkdownPreviewExample.Example;
10const NavMenu = MarkdownPreviewExample.NavMenu;
11
12<MarkdownPreviewExample
13  source={data.source}
14  components={data.components}
15  data={data.data}
16  title="MarkdownPreviewExample for React"
17  version={`v${VERSION}`}
18>
19  <Github href="https://github.com/uiwjs/react-markdown-preview-example" />
20  <Example>
21    <div>test</div>
22  </Example>
23</MarkdownPreviewExample>

1import PreviewExample from '@uiw/react-markdown-preview-example';
2
3<PreviewExample.NavMenu
4  title="Markdown Preview Example"
5  menus={[
6    <a target="_blank" href="https://uiwjs.github.io/react-markdown-preview/" rel="noopener noreferrer">Markdown</a>,
7    <a target="_blank" href="https://jaywcjlove.github.io/#/sponsor" rel="noopener noreferrer">Sponsor</a>
8  ]}
9/>

just markdown preview and run in markdown show react example.

1import MarkdownPreview from '@uiw/react-markdown-preview-example/markdown';
2import data from './docs/README.md';
3
4data.source     // => `README.md` raw string text
5data.components // => The component index object, the React component converted from the markdown indexed example. (need to configure meta)
6data.data       // => The component source code index object, the sample source code indexed from markdown. (need to configure meta)
7
8<Markdown source={data.source} data={data} />

1import type { MarkdownPreviewProps } from '@uiw/react-markdown-preview';
2import type { CodeBlockData } from 'markdown-react-code-preview-loader';
3export interface MarkdownProps extends MarkdownPreviewProps {
4  data: CodeBlockData;
5}
6export 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. The configuration and usage methods are consistent in Webpack:

1// .kktrc.ts
2import webpack, { Configuration } from 'webpack';
3import scopePluginOptions from '@kkt/scope-plugin-options';
4import { LoaderConfOptions } from 'kkt';
5
6export default (conf: Configuration, env: 'development' | 'production', options: LoaderConfOptions) => {
7  // ....
8  config.module.rules.forEach((ruleItem) => {
9    if (typeof ruleItem === 'object') {
10      if (ruleItem.oneOf) {
11        ruleItem.oneOf.unshift({
12          test: /.md$/,
13          use: [
14            {
15              loader: 'markdown-react-code-preview-loader',
16              options: { lang:["jsx","tsx"] },
17            },
18          ],
19        });
20      }
21    }
22  });
23  // ....
24  return conf;
25};

Or

1// .kktrc.ts
2import scopePluginOptions from '@kkt/scope-plugin-options';
3import { LoaderConfOptions, WebpackConfiguration } from 'kkt';
4import { mdCodeModulesLoader } from 'markdown-react-code-preview-loader';
5
6export default (conf: WebpackConfiguration, env: 'development' | 'production', options: LoaderConfOptions) => {
7  // ....
8  conf = mdCodeModulesLoader(conf);
9  // ....
10  return conf;
11};

src/react-app-env.d.ts

1declare var VERSION: string;
2declare module '*.md' {
3  import { CodeBlockData } from 'markdown-react-code-preview-loader';
4  const src: CodeBlockData;
5  export default src;
6}

Preview React Example

1import React from 'react';
2const Demo = () => <div>Preview React Example</div>
3export default Demo;

Note ⚠️: You need to add a special meta identifier to the code block example, and 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

1import React from 'react';
2const Demo = () => <div>Preview React Example: <b>mdx:preview</b></div>
3export default Demo;

1import React from 'react';
2const Demo = () => <div>Preview React Example: <b>mdx:preview&checkered=0</b></div>
3export default Demo;

Props

1import '@wcj/dark-mode';
2import type { PropsWithChildren } from 'react';
3import type { CodeBlockData } from 'markdown-react-code-preview-loader';
4import type { GitHubCornersProps } from '@uiw/react-github-corners';
5import type { MarkdownPreviewProps } from '@uiw/react-markdown-preview';
6declare function Github(props: GitHubCornersProps): null;
7declare function Corners(props: GlobalStore['darkMode']): null;
8declare function Example({ children }: PropsWithChildren): null;
9declare function NavMenu(props: NavMenuProps): null;
10export interface MarkdownPreviewExampleProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
11  source: string;
12  components: CodeBlockData['components'];
13  data: CodeBlockData['data'];
14  version?: string;
15  title?: JSX.Element | string;
16  markdownProps?: MarkdownPreviewProps;
17  exampleProps?: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>;
18  logo?: JSX.Element;
19  description?: JSX.Element | string;
20  disableCorners?: boolean;
21  disableDarkMode?: boolean;
22  disableHeader?: boolean;
23  disableBackToUp?: boolean;
24}
25declare const InternalMarkdownPreviewExample: import("react").ForwardRefExoticComponent<MarkdownPreviewExampleProps & import("react").RefAttributes<HTMLUListElement>>;
26type ExampleComponent = typeof InternalMarkdownPreviewExample & {
27  Example: typeof Example;
28  Github: typeof Github;
29  Corners: typeof Corners;
30  NavMenu: typeof NavMenu;
31};
32declare const MarkdownPreviewExample: ExampleComponent;
33export default MarkdownPreviewExample;
34export interface NavMenuProps {
35  title?: string;
36  logo?: React.ReactNode;
37  github?: string;
38  menus?: Array<React.AnchorHTMLAttributes<HTMLAnchorElement>>;
39}
40export interface GlobalStore {
41  corners: GitHubCornersProps;
42  darkMode: Partial<HTMLElementTagNameMap['dark-mode']>;
43  example?: React.ReactNode;
44  navMenu?: NavMenuProps;
45}

Development

Runs the project in development mode.

1# Step 1, run first, listen to the component compile and output the .js file
2# listen for compilation output type .d.ts file
3npm run watch
4# Step 2, development mode, listen to compile preview website instance
5npm run start

Builds the app for production to the build folder.

1npm 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!

Made with contributors.

License

Licensed under the MIT License.