react-marked-renderer

React Marked Renderer

A low-level component wrapper for marked that renders as React components instead of strings.

Check out the playground website to see how markdown is rendered with the default renderers or custom renderers and the API Documentation.

Installation

npm install react react-marked-renderer

Or with yarn:

yarn add react react-marked-renderer

Features

• render almost everything that is available by GitHub flavored markdown out of the box
  • the only exception is rendering html code itself
• allow custom renderers to implement complex components if desired or custom styles
• allows code highlighting
  • allow code language aliases/resolution with getLanguage
  • in the browser with highlightElement (can be asynchronous)
  • in node environments with highlightCode (synchronous only)

Note: Since the marked.lexer does not support custom extensions, neither does this library. I would like to support this feature in the future.

Usage

The main component within this library is the Markdown component.

Check out the Markdown tests and Markdown snapshots to see the default functionality.

Simple Example

import { render } from "react-dom";
import { Markdown } from "react-marked-renderer";

const markdown = `# Heading 1

This is some text that will be rendered as a paragraph.

Markdown defaults to the github-flavored markdown.
`;

render(<Markdown markdown={markdown} />, document.getElementById("root"));

Custom Renderers

Since the default renderers add no styles, you can define your own renderers to add styles or additional functionality.

import { useState } from "react";
import { render } from "react-dom";
import {
  DEFAULT_MARKDOWN_RENDERERS,
  ListRenderer,
  Markdown,
  Renderers,
  getTokensText,
} from "react-marked-renderer";
import { BrowserRouter as Router, Link } from "react-router-dom";

const renderers: Renderers = {
  ...DEFAULT_MARKDOWN_RENDERERS,
  link: function CustomLink({ href, title, children }) {
    // make links use html5 history and not cause reloads
    return (
      <Link to={href} title={title}>
        {children}
      </Link>
    );
  },

  blockquote: function Blockquote({ children }) {
    return <blockquote className="custom">{children}</blockquote>;
  },

  task: function Task({ defaultChecked, tokens, children }) {
    // hooks can be used in these renderers
    const id = useSluggedId(`${getTokensText(tokens)}-task`);
    const [checked, setChecked] = useState(defaultChecked);
    return (
      <li className="task-item">
        <input
          id={id}
          checked={checked}
          onChange={(event) => setChecked(event.currentTarget.checked)}
        />
        <label htmlFor={d}>{children}</label>
      </li>
    );
  },

  list: function List(props) {
    // can get the current renderers as well
    const renderers = useRenderers();
    const { listitem: ListItem } = renderers;
    const item = <ListItem>Content</ListItem>;

    // or just return the default renderer
    return <ListRenderer {...props} />;
  },
};

render(
  <Router>
    <Markdown markdown={markdown} renderers={renderers} />
  </Router>,
  document.getElementById("root")
);

PrismJS Code Highlighting (Browser)

To be able to highlight code in the browser, provide a highlightElement function that will modify a <code> element to be highlighted:

import { render } from "react-dom";
import {
  DEFAULT_MARKDOWN_RENDERERS,
  Markdown,
  Renderers,
} from "react-marked-renderer";
import Prism from "prismjs";
// import prism theme/components or use `babel-plugin-prismjs`

const renderers: Renderers = {
  ...DEFAULT_MARKDOWN_RENDERERS,
  codespan: function CodeSpan({ children }) {
    // just so it gets some prism styling
    return <code className="language-none">{children}</code>;
  },
};

render(
  <Markdown
    markdown={markdown}
    renderers={renderers}
    highlightElement={Prism.highlightElement}
  />,
  document.getElementById("root")
);

PrismJS Code Highlighting (Node and Browser)

If you want to highlight code in a node environment or allow the code to be highlighted for SSR and in the browser, provide a highlightCode function:

import { render } from "react-dom";
import {
  DEFAULT_MARKDOWN_RENDERERS,
  DangerouslyHighlight,
  GetCodeLanguage,
  Markdown,
  Renderers,
} from "react-marked-renderer";
import Prism from "prismjs";

const renderers: Renderers = {
  ...DEFAULT_MARKDOWN_RENDERERS,
  codespan: function CodeSpan({ children }) {
    // just so it gets some prism styling
    return <code className="language-none">{children}</code>;
  },
};

const getLanguage: GetCodeLanguage = (lang, _rawCode) => {
  // allow aliases
  lang = lang === "sh" ? "shell" : lang;

  // if the Prism doesn't support the language, default to nothing instead
  // of crashing
  if (!Prism.languages[lang]) {
    return "none";
  }

  return lang;
};

const highlightCode: DangerouslyHighlightCode = (code, lang) =>
  Prism.highlight(code, Prism.languages[lang], lang);

render(
  <Markdown
    markdown={markdown}
    renderers={renderers}
    getLanguage={getLanguage}
    highlightCode={highlightCode}
  />,
  document.getElementById("root")
);

What's the use-case?

This library mostly came up since I like to write documentation sites in markdown, but also apply custom styles as well as linking to other documentation pages using html5 history (no full page reloads).

Changelog

2.0.1 (2023-11-02)

Bug Fixes

• cypress: enable videos and save projectId (bcaab4f)
• esm: add exports for esm (ca85d5b), closes #196

Internal Changes

• ci: add missing -- to test command (876976a)
• ci: another attempt at fixing ci... (8613320)
• ci: another attempt at fixing cypress runner (4ebc9f9)
• ci: another ci fix attempt (10351fe)
• ci: hopefully fix cypress tests in github actions (f1ce62e)
• cypress: add cypress videos and screenshots to gitignore (6c18ae5)
• cypress: hopefully fix cypress in workflows (ba4dd0f)
• deps-dev: bump @octokit/core from 3.6.0 to 4.0.4 (48ccc25)
• deps: add renovate.json (51c795d)
• deps: bump terser from 5.7.2 to 5.14.2 (8a25996)
• dev-deps: bump all dev dependencies to latest (e3de1db)
• dev-deps: bump dev dependencies to latest (42bc710)
• dev-deps: bump dev dependencies to latest (2152a06)
• dev-deps: bump dev dependencies to latest (9935835)
• dev-deps: bump dev-deps to latest (f435506)
• dev-deps: bump jest and ts-jest to v28 (04c802b)
• dev-deps: set inquirer back to v8 (95c6fc9)
• fix eslint error (8f88586)
• fix missing prebuid command for website (c15d926)
• fix typo on cypress test name (ad0bfe4)
• github: fix pnpm version in workflow (7d3dd84)
• github: fix pnpm version in workflow (289b4e7)
• release: 2.0.0 (d7bf92c)
• remove dependabot workflow since I use pnpm (3b8a5e4)
• switch to pnpm (5ed1856)
• update release script notes and rollup config (ee982f7)
• update to use esm and @swc/jest (6c78524)
• website: fix styles and remove some features on mobile (d87cb0e)
• workflow: allow build to work in github actions (accd997)
• workflow: start recording cypress tests in main workflow (b42f20d)
• workflow: try adding additional git info for cypress Dashboard (fd3379d)
• workflow: update cypress tests to not require recording (0304b2d)
• workflow: upload cypress assets (970805e)