@molecule/app-markdown-react-markdown

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Markdown provider for @molecule/app-markdown, backed by the real react-markdown 10 library plus remark-gfm.

The core contract returns an HTML STRING (render(): { html: string; toc? }), but react-markdown renders React elements — so this bond renders that element tree to a static string with renderToStaticMarkup (react-dom/server). You still get real CommonMark parsing and full GitHub Flavored Markdown (tables, strikethrough, task lists, autolinks, footnotes) via remark-gfm.

Quick Start

import { provider } from '@molecule/app-markdown-react-markdown'
import { requireProvider, setProvider } from '@molecule/app-markdown'

setProvider(provider) // once, at app startup (bonds.ts)

const { html } = requireProvider().render('| a | b |\n| - | - |\n| 1 | 2 |')
// html === '<table>…</table>'  (a real GFM table)

Type

provider

Installation

npm install @molecule/app-markdown-react-markdown @molecule/app-markdown react react-dom react-markdown remark-gfm
npm install -D @types/react @types/react-dom

API

Interfaces

`ReactMarkdownConfig`

Provider-specific configuration for {@link createProvider}. These are the defaults baked into a provider instance; per-call {@link MarkdownOptions} (from @molecule/app-markdown) override the ones they share (sanitize, gfm, components).

interface ReactMarkdownConfig {
  /**
   * Whether to sanitize link/image URLs by default (the XSS URL gate). When
   * `true` (default) react-markdown's `defaultUrlTransform` strips dangerous
   * schemes (`javascript:`, `data:`, `vbscript:`, …); when `false` all schemes
   * pass through for trusted, app-authored content. Raw HTML in the source is
   * ALWAYS escaped to inert text regardless of this flag (react-markdown never
   * executes it), so `sanitize: false` only relaxes URL filtering — it does not
   * enable raw-HTML passthrough. Defaults to `true`.
   */
  sanitize?: boolean

  /**
   * Whether to enable GitHub Flavored Markdown (the `remark-gfm` plugin —
   * tables, strikethrough, task lists, autolinks, footnotes) by default.
   * Defaults to `true`.
   */
  gfm?: boolean

  /**
   * Extra remark plugins to run, appended after `remark-gfm` and the (optional)
   * hard-break transform. Use for additional markdown-AST extensions.
   */
  remarkPlugins?: MarkdownPluginList

  /**
   * Rehype plugins to run on the HTML AST (after `remark-rehype`), appended
   * after the built-in heading-id plugin. This is where a real syntax
   * highlighter (e.g. `rehype-highlight`) is wired in.
   */
  rehypePlugins?: MarkdownPluginList

  /**
   * Restrict the output to only these HTML tag names. Mutually exclusive with
   * {@link ReactMarkdownConfig.disallowedElements} — if both are set,
   * `allowedElements` wins.
   */
  allowedElements?: readonly string[]

  /** Drop these HTML tag names from the output (e.g. `['img']`). */
  disallowedElements?: readonly string[]

  /**
   * Custom component overrides keyed by tag name (react-markdown's
   * `Components`). Merged with any per-call `options.components`, which win.
   */
  components?: Components
}

Types

`MarkdownPluginList`

A list of remark or rehype plugins — react-markdown's PluggableList (a plugin function, a [plugin, options] tuple, or a preset). Re-derived from react-markdown's own Options so no extra dependency on unified is needed.

type MarkdownPluginList = NonNullable<Options['remarkPlugins']>

Functions

`createProvider(config)`

Creates a react-markdown provider instance.

function createProvider(config?: ReactMarkdownConfig): MarkdownProvider

config — Optional provider configuration (defaults for every render).

Returns: A configured {@link MarkdownProvider}.

Constants

`provider`

Default react-markdown provider instance (GFM + URL sanitization on).

const provider: MarkdownProvider

Core Interface

Implements @molecule/app-markdown interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/app-markdown'
import { provider } from '@molecule/app-markdown-react-markdown'

export function setupMarkdownReactMarkdown(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

@molecule/app-markdown ^1.0.1
react ^18.0.0 || ^19.0.0
react-dom ^18.0.0 || ^19.0.0

Runtime Dependencies

@molecule/app-markdown
react
react-dom
react-markdown
remark-gfm
GFM is real and on by default. Tables, ~~strikethrough~~, - [x] task lists, bare-URL autolinks, and footnotes all render. Set gfm: false (per call or in {@link ReactMarkdownConfig}) to fall back to plain CommonMark — a pipe table then renders as literal text.
Raw HTML is never executed. react-markdown does not include rehype-raw, so any raw HTML in the source (<script>, <b>, an onerror attribute) is escaped to inert text — the bond is XSS-safe for raw HTML unconditionally. The sanitize flag therefore governs only URL filtering: on (default) strips dangerous href/src schemes (javascript:, data:, …) via defaultUrlTransform; off lets all schemes through for trusted, app-authored content. sanitize: false does NOT enable raw-HTML passthrough. Keep sanitize on for user- or model-generated markdown.
Honored options: gfm, sanitize, breaks (soft breaks → <br>), linkTarget (_blank also adds rel="noopener noreferrer"), and components (custom tag overrides). Headings get slug ids so result.toc anchors resolve. For syntax highlighting, fenced code always carries a language-* class (highlighter-ready); to actually colorize, pass a rehype highlighter (e.g. rehype-highlight) via config.rehypePlugins.
{@link ReactMarkdownConfig} additionally exposes remarkPlugins, rehypePlugins, allowedElements, and disallowedElements for provider-level customization at {@link createProvider} time.
Wire it with setProvider() from @molecule/app-markdown or bond('markdown', provider) from @molecule/app-bond — both route through the shared registry; requireProvider() throws until one has run.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

Common markdown renders as real HTML wherever the app shows it (chat reply, comment, note, README preview): #..###### become <h1>..<h6>, **bold** a <strong>, *italic* an <em>, -/1. lists become <ul>/<ol> of <li>, [text](url) an <a> anchor, and a fenced code block a <pre><code> — not the raw */backticks shown as literal text.
GFM extras render when enabled (gfm, default on): a pipe table | a | b | becomes a real <table> with header + rows, and ![alt](src) an <img>.
The output tracks the source: editing the markdown updates the preview live — change a heading's text and its <h#> updates; add a list item and a new <li> appears. No stale or one-shot render.
SECURITY (XSS) — user- or model-supplied markdown is sanitized (sanitize, default on, the XSS gate): markdown containing a raw <script>alert(1)</script>, an <img src=x onerror=alert(1)>, or a [click](javascript:alert(1)) link must NOT execute and must NOT produce active markup — the script is stripped, the onerror is gone, and the link's href is neutralized. Verify in the browser: no alert fires, and DevTools shows no <script>, onerror, or javascript: in the rendered DOM. Never render untrusted content with sanitize: false.
Malformed markdown degrades gracefully — an unclosed **, a broken [link](, or a half-open code fence renders as readable text and never throws, blanks the view, or breaks the surrounding page.

`@molecule/app-markdown-react-markdown`

How it works

Reference