markdown-parser-react

Markdown Parser React

A flexible and feature-rich React component for rendering Markdown content with customizable styling, extensive formatting options, and robust typings.

Features

• 🚀 Full Markdown syntax support

• 💅 Customizable styling with CSS classes and inline styles

• 🔒 HTML sanitization

• ♿ Accessibility support

• 📱 Responsive image handling

• 🎨 Syntax highlighting for code blocks

• 📝 Task list support

• 📊 Table support with alignment options

• 🔗 Custom link handling

• 🎯 Definition lists

• 📑 Custom IDs for headers

• 🔢 Nested list support

• ➗ Supports Math Equations

Installation

Install Markdown Parser React using npm or yarn or pnpm:

npm  install  markdown-parser-react

# or

yarn  add  markdown-parser-react

# or

pnpm  add  markdown-parser-react

Basic Usage

The basic usage example demonstrates rendering a simple Markdown string:

import Markdown from "markdown-parser-react";

function MyComponent() {
  return <Markdown content="# Hello World
  This is **markdown** content." />;
}

Advanced Usage

In the advanced usage example, we see how you can configure the component with custom styling, classes, and additional features like task lists, code highlighting, and tables

import Markdown from "markdown-parser-react";

function BlogPost() {
  const markdownContent = `

# Welcome to My Blog

This is a _formatted_ paragraph with a [link](https://example.com).

- [x] Task 1

- [ ] Task 2

\`\`\`javascript

const hello = "world";

console.log(hello);

\`\`\`

| Column 1 | Column 2 |

|----------|----------|

| Cell 1 | Cell 2 |

`;

  return (
    <Markdown
      content={markdownContent}
      options={{
        customClasses: {
          headings: "blog-heading",

          paragraphs: "blog-paragraph",
        },

        customStyles: {
          headings: {
            color: "#2c3e50",

            fontFamily: "Georgia, serif",
          },
        },

        linkTarget: "_blank",

        sanitizeHtml: true,

        maxNestingLevel: 4,
      }}
      className="blog-content"
      asArticle={true}
      aria={{
        label: "Blog post content",

        describedBy: "blog-description",
      }}
    />
  );
}

Usage with Next.js

If you're using Next.js, you may encounter the "Text content does not match server-rendered HTML" error.

To avoid this issue, you can use next/dynamic to dynamically import the Markdown component, ensuring that it is only rendered on the client-side.

Here's how to use Markdown with Next.js:

import dynamic from "next/dynamic";

const Markdown = dynamic(
  () => import("markdown-parser-react").then((markdown) => markdown),

  {
    ssr: false,
  }
);

interface MyComponentProps {
  content: string;

  options?: {
    langPrefix?: string;
    linkTarget?: string; 
  };
}

export const MyComponent: React.FC<MyComponentProps> = ({
  content,
  options,
}) => {
  return (
    <div>
      <Markdown content={content} options={options} />
    </div>
  );
};

By using the next/dynamic function and passing ssr as false, we ensure that the Markdown component is only rendered on the client-side, preventing the mismatch error between server-rendered and client-rendered HTML in Next.js projects.

Configuration Options

Props

The MarkdownProps interface defines the properties that can be passed into the component. These props allow you to customize the behavior, appearance, and accessibility of the rendered Markdown.

Prop	Type	Description	Example
content	string	The Markdown content to be rendered. This is the main content of the component.	md<br># Hello World<br>**Bold text** [Link](https://example.com)
options	ParseOptions (optional)	Configuration options for the Markdown parser.
className	string (optional)	Additional CSS class names to be applied to the container.	className="my-markdown"
style	React.CSSProperties (optional)	Custom styles to be applied to the container.	style={{ backgroundColor: 'lightgray' }}
asArticle	boolean (optional)	Whether to wrap the content in an article element instead of a div. Recommended for semantic HTML when rendering full articles or blog posts. Defaults to false.	asArticle={true}
id	string (optional)	Custom ID to be applied to the container.	id="blog-post-1"
aria	{ label?: string, describedBy?: string } (optional)	Additional accessibility attributes for the container. label is the accessible name, and describedBy references an element that provides more information.	aria={{ label: 'Blog Content', describedBy: 'content-description' }}

ParseOptions

The ParseOptions interface provides configuration for parsing and rendering the Markdown content. It gives you the ability to customize how the content is parsed and displayed, including applying custom classes, styles, and controlling link behavior.

Option	Type	Description	Example
langPrefix	string (optional)	Prefix for language-specific code block classes.	langPrefix="language-"
customClasses	CustomClasses (optional)	Custom CSS classes for different Markdown elements.	{ headings: 'custom-heading', paragraphs: 'custom-paragraph' }
customStyles	CustomStyles (optional)	Custom CSS styles for different Markdown elements.	{ headings: { color: 'blue', fontFamily: 'Arial' } }
linkTarget	`"_blank"	"_self"	"_parent"
sanitizeHtml	boolean (optional)	Whether to sanitize HTML content to prevent XSS attacks. Defaults to false.	sanitizeHtml={true}
maxNestingLevel	number (optional)	Maximum allowed nesting level for lists. Defaults to 6.	maxNestingLevel={4}

Supported Markdown Features

Basic Formatting

• Headers (H1-H6)

• Bold and Italic text

• Strikethrough

• Links

• Images

• Blockquotes with citations

• Ordered and unordered lists

• Code blocks with syntax highlighting

Extended Features

• Task lists with checkboxes

• Tables with alignment options

• Definition lists

• Custom header IDs

• Math expressions ($...$)

• Superscript (^...^)

• Subscript (~...~)

• Highlighted text (==...==)

Code Block Example

```javascript

function hello() {
  console.log("Hello, world!");
}


```

Table Example

| Left | Center | Right |

|:-----|:------:|------:|

| L1 | C1 | R1 |

Customization

You can customize how the Markdown content is displayed by adjusting the appearance of different elements like headings, paragraphs, links, and more. Below are the options for customizing the styles and classes.

Custom Classes

You can pass your classNames to customClasses config inside the options object passed as props to the component

Element	Type	Description	Example
headings	string	Custom class for headings (H1-H6).	headings:"custom-heading-class"
paragraphs	string	Custom class for paragraphs.	paragraphs:"custom-paragraph-class"
lists	string	Custom class for lists (ordered and unordered).	lists:"custom-list-class"
blockquotes	string	Custom class for blockquotes.	blockquotes:"custom-blockquote-class"
codeBlocks	string	Custom class for code blocks.	codeBlocks="custom-code-class"
tables	string	Custom class for tables.	tables:"custom-table-class"
links	string	Custom class for links.	links:"custom-link-class"
images	string	Custom class for images.	images:"custom-image-class"

Custom Styles

You can pass your styles to the customStyles property inside the option object.

Element	Type	Description	Example
headings	CSSProperties	Custom styles for headings (H1-H6).	headings:{{ color: 'blue', fontSize: '2em' }}
paragraphs	CSSProperties	Custom styles for paragraphs.	paragraphs:{{ lineHeight: '1.5' }}
lists	CSSProperties	Custom styles for lists (ordered and unordered).	lists:{{ marginLeft: '20px' }}
blockquotes	CSSProperties	Custom styles for blockquotes.	blockquotes:{{ borderLeft: '4px solid gray' }}
codeBlocks	CSSProperties	Custom styles for code blocks.	codeBlocks:{{ backgroundColor: 'black', color: 'white' }}
tables	CSSProperties	Custom styles for tables.	tables:{{ borderCollapse: 'collapse' }}
links	CSSProperties	Custom styles for links.	links:{{ textDecoration: 'underline' }}
images	CSSProperties	Custom styles for images.	images:{{ maxWidth: '100%' }}

Default Styling

The component comes with default styles that can be imported:

import { defaultStyles } from "markdown-parser-react";

// In your global CSS or styled-components

const GlobalStyle = createGlobalStyle`

${defaultStyles}

`;

Accessibility

The component follows WCAG guidelines and provides:

• Semantic HTML structure

• ARIA attributes support

• Keyboard navigation for interactive elements

• Screen reader-friendly content structure

Browser Support

• Chrome (latest)

• Firefox (latest)

• Safari (latest)

• Edge (latest)

• IE11 (with appropriate polyfills)

Contributing

Contributions are welcome! Please read our contributing guidelines for more information.

Issues

If you encounter any issues or have suggestions for improvements, please report them on the GitHub Issues page

Hire Me

If you need a freelance developer for your project, feel free to contact me at LinkedIn I have experience with React, Next.js, TypeScript, and Node.js, and I would be happy to discuss your project with you.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Happy Coding Everyone! 🧑🏽‍💻