Rendering Markdown in React: Architecture, Ecosystem, and Maintenance

Handling Markdown in the React ecosystem isn't a one-size-fits-all task. The right tool depends entirely on your framework, your need for security, and how much you need to customize the rendering pipeline. Let's break down gatsby-transformer-remark, react-markdown, react-remark, and remarkable to see where each fits in a professional architecture.

🏗️ Core Architecture: Build-Time vs. Runtime vs. Legacy

The most critical distinction is when and how the Markdown is processed.

gatsby-transformer-remark operates at build time. It is not a React component you render; it is a Gatsby plugin that reads .md files from your disk, parses them, and injects them into your GraphQL data layer. You query the data, and Gatsby gives you pre-processed HTML or AST nodes.

// gatsby-transformer-remark: Usage in a Gatsby Page Component
import { graphql } from 'gatsby';

export const query = graphql`
  query {
    markdownRemark(frontmatter: { slug: { eq: "/blog-post" } }) {
      html // Pre-processed HTML string generated at build time
      frontmatter {
        title
      }
    }
  }
`;

export default function BlogPost({ data }) {
  // Directly injecting HTML (Gatsby handles sanitization internally for this plugin)
  return <div dangerouslySetInnerHTML={{ __html: data.markdownRemark.html }} />;
}

react-markdown operates at runtime (or server-render time) as a React Component. It takes a Markdown string as a prop, parses it safely, and returns a tree of React elements. It does not output HTML strings, avoiding the need for dangerouslySetInnerHTML.

// react-markdown: Usage in any React App
import ReactMarkdown from 'react-markdown';

const content = "# Hello\nThis is **bold** text.";

export default function Article() {
  // Renders as React components, not raw HTML
  return <ReactMarkdown>{content}</ReactMarkdown>;
}

react-remark is a hybrid. It is a wrapper around react-markdown that allows you to inject remark plugins into the parsing pipeline before rendering to React. It gives you the customization of the remark ecosystem with the safety of react-markdown.

// react-remark: Usage with plugins
import { ReactMarkdown } from 'react-markdown';
import remarkGfm from 'remark-gfm'; // GitHub Flavored Markdown
import remarkMath from 'remark-math';

export default function TechnicalDoc({ content }) {
  return (
    <ReactMarkdown
      remarkPlugins={[remarkGfm, remarkMath]}
      children={content}
    />
  );
}

remarkable is a legacy parser. It runs at runtime but outputs a raw HTML string. To use it in React, you must force React to render raw HTML, which bypasses React's security protections.

// remarkable: Legacy approach (Not Recommended)
import Remarkable from 'remarkable';

const md = new Remarkable();
const content = "# Hello\n[Link](http://evil.com)";
const htmlString = md.render(content);

export default function LegacyView() {
  // DANGEROUS: Requires dangerouslySetInnerHTML
  // Vulnerable to XSS if content is user-generated
  return <div dangerouslySetInnerHTML={{ __html: htmlString }} />;
}

🔒 Security Model: Safe Components vs. Raw HTML

Security is the biggest differentiator between modern and legacy approaches.

react-markdown and react-remark are secure by default. They parse Markdown into an Abstract Syntax Tree (AST) and then render it as React elements. They automatically strip dangerous HTML tags (like <script>) unless you explicitly configure them to allow specific HTML. This makes them safe for rendering user-generated content.

// react-markdown: Safe by default
// Even if content contains <script>, it will be escaped or ignored
<ReactMarkdown>{userSubmittedContent}</ReactMarkdown>

// Customizing allowed components safely
<ReactMarkdown
  components={{
    h1: ({node, ...props}) => <h1 className="text-3xl" {...props} />
  }}
>
  {content}
</ReactMarkdown>

gatsby-transformer-remark handles security at the build step. Since the content is usually authored by developers or trusted editors in the CMS/filesystem, the risk is lower. However, it outputs an HTML string, so if you modify that string before rendering, you must be careful.

// gatsby-transformer-remark: Trusted content flow
// Content is sanitized during the Gatsby build process
const { html } = data.markdownRemark;
// Safe to render if content source is trusted
<div dangerouslySetInnerHTML={{ __html: html }} />

remarkable has no built-in React security. It blindly converts Markdown to HTML. If a user inputs ![x](onerror=alert(1)), remarkable might render it as an image tag with an executable script unless you manually configure a sanitizer. This extra step is error-prone and why this package is risky for modern apps.

// remarkable: Manual sanitization required (Error Prone)
const md = new Remarkable({ html: true, linkify: true });
// You MUST add a separate sanitizer library to prevent XSS
// const clean = DOMPurify.sanitize(md.render(content)); 
<div dangerouslySetInnerHTML={{ __html: clean }} />

🔌 Extensibility: Plugins and Customization

How easy is it to add features like tables, math, or custom heading IDs?

react-remark shines here. Because it exposes the remarkPlugins prop, you can drop in any plugin from the massive unified ecosystem. Need GitHub tables? Math formulas? Autolinks? Just install the plugin and pass it in.

// react-remark: Easy plugin integration
import remarkGfm from 'remark-gfm';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex'; // For rendering math

<ReactMarkdown
  remarkPlugins={[remarkGfm, remarkMath]}
  rehypePlugins={[rehypeKatex]}
>
  {content}
</ReactMarkdown>

react-markdown supports plugins too (in newer versions), but react-remark was historically the dedicated bridge. Now, react-markdown accepts remarkPlugins directly, making the distinction thinner, but react-remark documentation often highlights complex pipeline configurations.

// react-markdown (v6+): Direct plugin support
import remarkGfm from 'remark-gfm';

<ReactMarkdown remarkPlugins={[remarkGfm]}>
  {content}
</ReactMarkdown>

gatsby-transformer-remark uses a Gatsby-specific plugin system. You configure plugins in gatsby-config.js. It's powerful but locked into the Gatsby ecosystem. You cannot use these plugins outside of Gatsby.

// gatsby-config.js: Plugin configuration
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          `gatsby-remark-prismjs`, // Syntax highlighting
          `gatsby-remark-images`,  // Image processing
        ],
      },
    },
  ],
};

remarkable has limited extensibility. It allows some rule customization, but it lacks the rich ecosystem of plugins available for remark/rehype. Adding complex features often requires writing custom parser rules, which is difficult and brittle.

// remarkable: Limited custom rules
const md = new Remarkable();
md.use(function (md) {
  // Hard to write custom rules compared to remark plugins
  md.inline.ruler.enable(['ins', 'mark']);
});

📦 Maintenance and Future-Proofing

This is the dealbreaker for remarkable.

• react-markdown and react-remark: Actively maintained. They follow modern React patterns (hooks, functional components) and keep up with the unified ecosystem updates.
• gatsby-transformer-remark: Actively maintained only if you are on Gatsby. If Gatsby evolves, this plugin evolves. It is stable for Gatsby v4/v5.
• remarkable: Unmaintained. The last significant updates were years ago. It does not support modern ES modules well out of the box without bundler tweaks, and it has known security issues that are not being patched. Do not start new projects with this.

🌐 Real-World Scenarios

Scenario 1: A Gatsby Blog

You are building a marketing site or blog with Gatsby. Content lives in src/pages/blog.

• ✅ Best choice: gatsby-transformer-remark
• Why? It integrates with GraphQL, handles image optimization via gatsby-remark-images, and generates static HTML for maximum performance.

// Gatsby Page
export const query = graphql`{ markdownRemark { html } }`;
<div dangerouslySetInnerHTML={{ __html: data.markdownRemark.html }} />

Scenario 2: A Next.js Dashboard with User Comments

You have a Next.js app where users can post comments in Markdown.

• ✅ Best choice: react-markdown
• Why? It renders safely on the server and client, prevents XSS attacks from malicious users, and requires no build-time processing.

// Next.js Component
<ReactMarkdown>{userComment}</ReactMarkdown>

Scenario 3: A Technical Documentation Site

You need to render complex docs with tables, math equations, and code highlighting.

• ✅ Best choice: react-markdown (with remark-gfm and rehype-highlight)
• Why? You need the plugin ecosystem to handle tables and math, which standard Markdown doesn't support.

<ReactMarkdown
  remarkPlugins={[remarkGfm, remarkMath]}
  rehypePlugins={[rehypeKatex, rehypeHighlight]}
>
  {docContent}
</ReactMarkdown>

Scenario 4: Legacy Migration

You are maintaining an old app using remarkable.

• ⚠️ Action: Plan to migrate to react-markdown.
• Why? remarkable is a security liability. The migration involves replacing md.render() with the <ReactMarkdown> component and removing dangerouslySetInnerHTML.

📊 Summary Table

💡 Final Recommendation

If you are using Gatsby, gatsby-transformer-remark is the correct architectural choice for your content layer. It leverages Gatsby's strengths in static generation.

For all other React projects, react-markdown is the industry standard. It is secure, fast, and flexible. If you need advanced features like math or tables, simply add the relevant remark plugins to react-markdown (or use react-remark if you prefer its specific API for complex pipelines).

Avoid remarkable entirely. It represents an older pattern of rendering HTML strings that conflicts with modern React's component model and security best practices. The cost of migrating away from it later is far higher than starting with react-markdown today.