@draftbase/renderer 0.4.1 → 0.4.3

package/README.md

@@ -232,6 +232,31 @@ import { toHtml } from "@draftbase/renderer";
 const html = await toHtml(entry.fields.body);
 ```
 
+By default, custom tags in the source (`<Callout>`, `<EntryLink>`, ...) pass through as literal HTML — `toHtml` produces a plain string, not a React tree, so there's no component tree to substitute into. Pass `components` to render one to an HTML string instead, keyed by tag name (case-insensitive):
+
+```ts
+const html = await toHtml(entry.fields.body, {
+  components: {
+    Callout: (props, childrenHtml) => `<div class="callout-${props.type}">${childrenHtml}</div>`,
+  },
+  externalLinks: true, // adds target="_blank" rel="noopener noreferrer" to off-site <a> tags
+});
+```
+
+Unlike a React `components` map, each prop always arrives as a string — real HTML parsing, not JSX evaluation, so `count="3"` is `"3"`, never `3`. `childrenHtml` is the tag's contents already rendered to HTML, with any nested custom tags resolved first.
+
+`EntryLink` gets a default (`<a href="/entries/{id}">`) the moment `components` is passed at all, same as the React renderer's default — override it the same way as any other tag:
+
+```ts
+const html = await toHtml(entry.fields.body, {
+  components: {
+    EntryLink: (props, childrenHtml) => `<a href="/blog/${props.id}">${childrenHtml}</a>`,
+  },
+});
+```
+
+Omit `components` entirely and every custom tag, `EntryLink` included, stays literal HTML (previous behavior); omit `externalLinks` and links are left as-is.
+
 ## Custom components
 
 Content can invoke JSX components by name inside the MDX source (e.g. `<Callout type="warning">...</Callout>`). Pass the implementations:

package/dist/MDXContent.d.ts

@@ -9,19 +9,15 @@ export interface CompiledMDX {
 }
 export type { FailedMDX };
 /**
- * Compiles raw MDX/markdown into a renderable React component — no DOM assumptions,
- * safe to call from a client-side effect or a Next.js Server Component (the
- * `MDXContent` component below does the latter). Standard markdown elements (`p`,
- * `h1`, `table`, ...) render via real DOM tags with zero setup; only a JSX component
- * with no built-in default (e.g. `<Callout>`) needs `components`.
+ * Compiles raw MDX/markdown into a renderable React component — no DOM assumptions, safe for client effects or RSC.
+ * Standard markdown elements render via real DOM tags with zero setup; only a JSX component with no built-in default needs `components`.
  */
 export declare function compileMDX(source: string): Promise<CompiledMDX | FailedMDX>;
 export interface MDXContentProps {
     /** Raw MDX/markdown string, e.g. an entry's rich text field. */
     source: string;
-    /** Custom components available by name inside the MDX source (e.g. `<Callout>`), and/or
-     * overrides for standard markdown elements (`p`, `h1`, `a`, `img`, ...) — required on
-     * non-DOM renderers such as React Native, which have no intrinsic `div`/`p`/`a` tags. */
+    /** Custom components available by name inside the MDX source, and/or overrides for standard markdown elements —
+     * required on non-DOM renderers such as React Native, which have no intrinsic `div`/`p`/`a` tags. */
     components?: MDXComponents;
     /** Skip the default `db-content` styling class. */
     unstyled?: boolean;
@@ -35,8 +31,7 @@ export interface MDXContentProps {
     errorTag?: ElementType;
 }
 /**
- * Next.js Server Component wrapper around {@link compileMDX}. For non-RSC React (client-side
- * web, React Native, Remix, ...), call `compileMDX` directly from your own data loader/effect
- * and render `Content` yourself — `await` inside a component body only works as an RSC.
+ * Next.js Server Component wrapper around {@link compileMDX}. For non-RSC React, call `compileMDX` directly instead —
+ * `await` inside a component body only works as an RSC.
  */
 export declare function MDXContent({ source, components, unstyled, className, wrapperTag, errorTag, }: MDXContentProps): Promise<ReactNode>;

package/dist/MDXContent.js

@@ -5,19 +5,15 @@ import { wrapperClassName } from "./wrapperClassName.js";
 import { MDXErrorBoundary } from "./MDXErrorBoundary.js";
 const defaultComponents = { EntryLink: makeDefaultEntryLink(runtime) };
 /**
- * Compiles raw MDX/markdown into a renderable React component — no DOM assumptions,
- * safe to call from a client-side effect or a Next.js Server Component (the
- * `MDXContent` component below does the latter). Standard markdown elements (`p`,
- * `h1`, `table`, ...) render via real DOM tags with zero setup; only a JSX component
- * with no built-in default (e.g. `<Callout>`) needs `components`.
+ * Compiles raw MDX/markdown into a renderable React component — no DOM assumptions, safe for client effects or RSC.
+ * Standard markdown elements render via real DOM tags with zero setup; only a JSX component with no built-in default needs `components`.
  */
 export async function compileMDX(source) {
     return compileMDXCore(source, runtime, defaultComponents);
 }
 /**
- * Next.js Server Component wrapper around {@link compileMDX}. For non-RSC React (client-side
- * web, React Native, Remix, ...), call `compileMDX` directly from your own data loader/effect
- * and render `Content` yourself — `await` inside a component body only works as an RSC.
+ * Next.js Server Component wrapper around {@link compileMDX}. For non-RSC React, call `compileMDX` directly instead —
+ * `await` inside a component body only works as an RSC.
  */
 export async function MDXContent({ source, components, unstyled, className, wrapperTag = "div", errorTag = "p", }) {
     const Wrapper = wrapperTag;

package/dist/MDXContent.test.js

@@ -1,9 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { MDXContent } from "./MDXContent.js";
-// Smoke test for the Next.js App Router / RSC entry point — MDXContent is an async
-// Server Component; call it directly (as React's RSC runtime would) and inspect the
-// element tree it returns, same style as compileMDX.test.ts.
+// MDXContent is an async Server Component; call it directly (as React's RSC runtime would) and inspect the returned element tree.
 test("MDXContent wraps compiled MDX in the styled wrapper element", async () => {
     const element = (await MDXContent({ source: "# Hello" }));
     assert.equal(element.type, "div");

package/dist/MDXErrorBoundary.js

@@ -1,9 +1,7 @@
 "use client";
 import { Component } from "react";
-// Catches render-time errors from compiled MDX content — most commonly a JSX component
-// referenced in the source (e.g. `<Callout>`, `<EntryLink>`) that wasn't supplied in
-// `components`. Without this, that throws "Element type is invalid" and crashes the whole
-// page instead of just the content block.
+// Catches render-time errors from compiled MDX content — most commonly a JSX component referenced in the
+// source but missing from `components`, which otherwise throws and crashes the whole page.
 export class MDXErrorBoundary extends Component {
     state = { hasError: false };
     static getDerivedStateFromError() {

package/dist/compileMDX.test.js

@@ -3,10 +3,8 @@ import test from "node:test";
 import { compileMDX as compileReactMDX } from "./MDXContent.js";
 import { compileMDX as compileVueMDX } from "./vue.js";
 const SOURCE = "# Hello\n\nWorld";
-/** compileMDX's Content is wrapped to merge in default components (see core.ts) —
- * unwrap by directly invoking each function-typed element until reaching real output,
- * same "call it like a plain function" style as the rest of these tests (no renderer
- * mounted). */
+/** Content is wrapped to merge in default components (see core.ts) — unwrap by invoking each
+ * function-typed element until reaching real output (no renderer mounted). */
 function resolve(element) {
     return typeof element.type === "function"
         ? resolve(element.type(element.props))

package/dist/core.d.ts

@@ -9,19 +9,12 @@ export interface FailedMDX {
     error: unknown;
 }
 /**
- * Shared MDX-to-component evaluation. Parameterized by JSX runtime (React's
- * `react/jsx-runtime`, a Vue `h()`-based shim, ...) so each framework entry point
- * supplies its own without duplicating the remark/rehype pipeline.
- *
- * `defaultComponents`, when given, are merged underneath whatever the caller passes
- * as `Content`'s own `components` prop (caller always wins per-tag) — this is what
- * lets a framework entry point ship working defaults (e.g. a default `EntryLink`,
- * or React Native's Text/View mapping) without requiring a mapping up front.
+ * Shared MDX-to-component evaluation, parameterized by JSX runtime so each framework entry point avoids duplicating
+ * the remark/rehype pipeline. `defaultComponents`, when given, are merged underneath the caller's own `components` (caller always wins per-tag).
  */
 export declare function compileMDXCore<TComponent>(source: string, jsxRuntime: JsxRuntime, defaultComponents?: Record<string, unknown>): Promise<CompiledMDX<TComponent> | FailedMDX>;
-/** Default `EntryLink` for a given JSX runtime — renders `<a href="/entries/{id}">`.
- * Covers the common case (a plain link to the entry's default route); apps that
- * route entries differently still override it by passing `components.EntryLink`. */
+/** Default `EntryLink` for a given JSX runtime — renders `<a href="/entries/{id}">`; apps that
+ * route entries differently override it by passing `components.EntryLink`. */
 export declare function makeDefaultEntryLink(jsxRuntime: JsxRuntime): ({ id, children }: {
     id?: string;
     children?: unknown;

package/dist/core.js

@@ -2,14 +2,8 @@ import { evaluate } from "@mdx-js/mdx";
 import remarkGfm from "remark-gfm";
 import rehypeSlug from "rehype-slug";
 /**
- * Shared MDX-to-component evaluation. Parameterized by JSX runtime (React's
- * `react/jsx-runtime`, a Vue `h()`-based shim, ...) so each framework entry point
- * supplies its own without duplicating the remark/rehype pipeline.
- *
- * `defaultComponents`, when given, are merged underneath whatever the caller passes
- * as `Content`'s own `components` prop (caller always wins per-tag) — this is what
- * lets a framework entry point ship working defaults (e.g. a default `EntryLink`,
- * or React Native's Text/View mapping) without requiring a mapping up front.
+ * Shared MDX-to-component evaluation, parameterized by JSX runtime so each framework entry point avoids duplicating
+ * the remark/rehype pipeline. `defaultComponents`, when given, are merged underneath the caller's own `components` (caller always wins per-tag).
  */
 export async function compileMDXCore(source, jsxRuntime, defaultComponents) {
     try {
@@ -37,9 +31,8 @@ function withDefaultComponents(Content, defaults, jsxRuntime) {
         });
     };
 }
-/** Default `EntryLink` for a given JSX runtime — renders `<a href="/entries/{id}">`.
- * Covers the common case (a plain link to the entry's default route); apps that
- * route entries differently still override it by passing `components.EntryLink`. */
+/** Default `EntryLink` for a given JSX runtime — renders `<a href="/entries/{id}">`; apps that
+ * route entries differently override it by passing `components.EntryLink`. */
 export function makeDefaultEntryLink(jsxRuntime) {
     return function EntryLink({ id, children }) {
         return jsxRuntime.jsx("a", { href: id ? `/entries/${id}` : undefined, children });

package/dist/reactNative.d.ts

@@ -10,21 +10,8 @@ export interface CompiledMDX {
 }
 export type { FailedMDX };
 /**
- * Wires up a React Native `compileMDX` with default Text/View/Image mappings for
- * every standard markdown element (and `EntryLink`), so a project sets up its RN
- * primitives once instead of mapping every tag on every call:
- *
- * ```ts
- * import { Text, View, Image } from "react-native";
- * import { createReactNativeRenderer } from "@draftbase/renderer/react-native";
- *
- * const { compileMDX } = createReactNativeRenderer({ Text, View, Image });
- * ```
- *
- * Ships default styling that mirrors the web look (heading scale, link color, table
- * layout, ...) — pass `styleOptions.unstyled` to drop it, or `styleOptions.styles` to
- * override specific tags (`{ h1: { fontSize: 32 } }`). Pass `components` on the
- * returned `Content` to override individual tags' component, same as the web entry point.
+ * Wires up a React Native `compileMDX` with default Text/View/Image mappings for every standard markdown element
+ * (and `EntryLink`), so a project sets up its RN primitives once instead of mapping every tag on every call.
  */
 export declare function createReactNativeRenderer(primitives: ReactNativePrimitives, styleOptions?: ReactNativeStyleOptions): {
     compileMDX: (source: string) => Promise<CompiledMDX | FailedMDX>;

package/dist/reactNative.js

@@ -2,26 +2,44 @@ import * as runtime from "react/jsx-runtime";
 import { compileMDXCore } from "./core.js";
 import { buildReactNativeComponents, } from "./reactNativeComponents.js";
 /**
- * Wires up a React Native `compileMDX` with default Text/View/Image mappings for
- * every standard markdown element (and `EntryLink`), so a project sets up its RN
- * primitives once instead of mapping every tag on every call:
- *
- * ```ts
- * import { Text, View, Image } from "react-native";
- * import { createReactNativeRenderer } from "@draftbase/renderer/react-native";
- *
- * const { compileMDX } = createReactNativeRenderer({ Text, View, Image });
- * ```
- *
- * Ships default styling that mirrors the web look (heading scale, link color, table
- * layout, ...) — pass `styleOptions.unstyled` to drop it, or `styleOptions.styles` to
- * override specific tags (`{ h1: { fontSize: 32 } }`). Pass `components` on the
- * returned `Content` to override individual tags' component, same as the web entry point.
+ * Wires up a React Native `compileMDX` with default Text/View/Image mappings for every standard markdown element
+ * (and `EntryLink`), so a project sets up its RN primitives once instead of mapping every tag on every call.
  */
 export function createReactNativeRenderer(primitives, styleOptions) {
     const defaultComponents = buildReactNativeComponents(primitives, styleOptions);
     async function compileMDX(source) {
-        return compileMDXCore(source, runtime, defaultComponents);
+        const result = await compileMDXCore(source, runtime, defaultComponents);
+        if (!result.ok)
+            return result;
+        // MDX bakes the source's literal inter-block whitespace into the compiled output as bare
+        // "\n" string children of the root Fragment (e.g. between a heading and the paragraph after
+        // it). React Native throws on a bare string child that isn't inside a <Text>, so those need
+        // stripping here — element-mapped tags already handle it themselves (see reactNativeComponents.ts).
+        const Content = result.Content;
+        // withDefaultComponents (core.ts) wraps the compiled MDX component in one props-forwarding
+        // layer, so unwrap exactly that to reach the actual root element (a Fragment for a multi-block
+        // document, or a single mapped element like Text/View otherwise) before stripping whitespace.
+        // Calling any further would start invoking the RN primitives (Text/View/Image) themselves.
+        const RootWithoutWhitespace = (props) => {
+            const wrapped = Content(props);
+            const rootElement = typeof wrapped.type === "function"
+                ? wrapped.type(wrapped.props)
+                : wrapped;
+            return stripWhitespaceRootChildren(rootElement);
+        };
+        return {
+            ok: true,
+            Content: RootWithoutWhitespace,
+        };
     }
     return { compileMDX };
 }
+function stripWhitespaceRootChildren(element) {
+    const children = element.props?.children;
+    if (!Array.isArray(children))
+        return element;
+    const filtered = children.filter((child) => typeof child !== "string" || child.trim() !== "");
+    if (filtered.length === children.length)
+        return element;
+    return runtime.jsxs(element.type, { ...element.props, children: filtered }, element.key ?? undefined);
+}

package/dist/reactNative.test.js

@@ -6,9 +6,8 @@ const Text = () => null;
 const View = () => null;
 const Image = () => null;
 const LEAVES = [Text, View, Image];
-/** Unwraps nested function-component elements (the default-components wrapper, the
- * per-tag style wrapper, ...) down to the RN primitive actually used, without calling
- * into the primitive itself (Text/View/Image are opaque leaves here, not JSX). */
+/** Unwraps nested function-component elements down to the RN primitive actually used,
+ * without calling into it (Text/View/Image are opaque leaves here, not JSX). */
 function resolve(element) {
     return typeof element.type === "function" && !LEAVES.includes(element.type)
         ? resolve(element.type(element.props))

package/dist/reactNativeComponents.d.ts

@@ -25,12 +25,8 @@ export interface ReactNativeStyleOptions {
     styles?: Partial<Record<string, Record<string, unknown>>>;
 }
 /**
- * Default MDX `components` map for React Native, built from its Text/View/Image
- * primitives. RN has no intrinsic host tags for `p`/`h1`/`a`/etc the way web React
- * does, so every standard markdown element needs an explicit mapping — this covers
- * the common ones, styled to match the web default look (heading scale, link color,
- * table layout, ...), so a project only wires up the three RN primitives once (via
- * `createReactNativeRenderer`) instead of mapping and styling every tag itself.
+ * Default MDX `components` map for React Native, built from its Text/View/Image primitives. RN has no intrinsic
+ * host tags for `p`/`h1`/`a`/etc the way web React does, so every standard markdown element needs an explicit mapping.
  */
 export declare function buildReactNativeComponents({ Text, View, Image }: ReactNativePrimitives, { unstyled, styles }?: ReactNativeStyleOptions): {
     p: ComponentType<{
@@ -138,27 +134,18 @@ export declare function buildReactNativeComponents({ Text, View, Image }: ReactN
         children?: ReactNode;
         style?: unknown;
     }) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>);
-    ul: ComponentType<{
+    ul: (props: {
         children?: ReactNode;
         style?: unknown;
-    }> | ((props: {
-        children?: ReactNode;
-        style?: unknown;
-    }) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>);
-    ol: ComponentType<{
-        children?: ReactNode;
-        style?: unknown;
-    }> | ((props: {
-        children?: ReactNode;
-        style?: unknown;
-    }) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>);
-    blockquote: ComponentType<{
+    }) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    ol: (props: {
         children?: ReactNode;
         style?: unknown;
-    }> | ((props: {
+    }) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    blockquote: (props: {
         children?: ReactNode;
         style?: unknown;
-    }) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>);
+    }) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     hr: ComponentType<{
         children?: ReactNode;
         style?: unknown;

package/dist/reactNativeComponents.js

@@ -1,12 +1,8 @@
 import * as runtime from "react/jsx-runtime";
 import { defaultReactNativeStyles } from "./reactNativeStyles.js";
 /**
- * Default MDX `components` map for React Native, built from its Text/View/Image
- * primitives. RN has no intrinsic host tags for `p`/`h1`/`a`/etc the way web React
- * does, so every standard markdown element needs an explicit mapping — this covers
- * the common ones, styled to match the web default look (heading scale, link color,
- * table layout, ...), so a project only wires up the three RN primitives once (via
- * `createReactNativeRenderer`) instead of mapping and styling every tag itself.
+ * Default MDX `components` map for React Native, built from its Text/View/Image primitives. RN has no intrinsic
+ * host tags for `p`/`h1`/`a`/etc the way web React does, so every standard markdown element needs an explicit mapping.
  */
 export function buildReactNativeComponents({ Text, View, Image }, { unstyled, styles } = {}) {
     const styleFor = (tag) => unstyled ? styles?.[tag] : { ...defaultReactNativeStyles[tag], ...styles?.[tag] };
@@ -16,6 +12,19 @@ export function buildReactNativeComponents({ Text, View, Image }, { unstyled, st
             return Base;
         return (props) => runtime.jsx(Base, { ...props, style: props.style ? [style, props.style] : style });
     }
+    // MDX bakes the source's literal formatting whitespace ("\n" between block elements) into the
+    // compiled JSX as string children, even though structurally these tags never hold real text.
+    // React Native's Text/View don't tolerate a bare string child of View, so container tags need it
+    // stripped — Text-mapped tags (p, li, td, ...) keep it, since inline whitespace there is real content.
+    function stripWhitespaceChildren(children) {
+        if (Array.isArray(children))
+            return children.filter((child) => typeof child !== "string" || child.trim() !== "");
+        return typeof children === "string" && children.trim() === "" ? undefined : children;
+    }
+    function container(Base, tag) {
+        const Styled = styled(Base, tag);
+        return (props) => runtime.jsx(Styled, { ...props, children: stripWhitespaceChildren(props.children) });
+    }
     const Img = ({ src, alt }) => runtime.jsx(Image, {
         source: { uri: src },
         accessibilityLabel: alt,
@@ -38,9 +47,9 @@ export function buildReactNativeComponents({ Text, View, Image }, { unstyled, st
         li: styled(Text, "li"),
         th: styled(Text, "th"),
         td: styled(Text, "td"),
-        ul: styled(View, "ul"),
-        ol: styled(View, "ol"),
-        blockquote: styled(View, "blockquote"),
+        ul: container(View, "ul"),
+        ol: container(View, "ol"),
+        blockquote: container(View, "blockquote"),
         hr: styled(View, "hr"),
         table: styled(View, "table"),
         thead: View,

package/dist/reactNativeComponents.test.js

@@ -1,9 +1,8 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { buildReactNativeComponents } from "./reactNativeComponents.js";
-// Stand-ins for react-native's Text/View/Image — this package doesn't depend on
-// react-native itself (it only resolves inside Metro, not plain Node), so the mapping
-// logic is tested against fakes with the same shape.
+// Stand-ins for react-native's Text/View/Image — this package doesn't depend on react-native itself
+// (it only resolves inside Metro, not plain Node), so the mapping is tested against fakes with the same shape.
 const Text = () => null;
 const View = () => null;
 const Image = () => null;

package/dist/reactNativeStyles.d.ts

@@ -1,4 +1,3 @@
-/** Default per-tag style objects for the React Native preset — mirrors `styles.css`'s
- * web defaults (heading scale, link color/underline, code/blockquote treatment, list
- * spacing) so RN output looks like the web default instead of unstyled plain text. */
+/** Default per-tag style objects for the React Native preset — mirrors `styles.css`'s web defaults
+ * so RN output looks like the web default instead of unstyled plain text. */
 export declare const defaultReactNativeStyles: Record<string, Record<string, unknown>>;

package/dist/reactNativeStyles.js

@@ -1,6 +1,5 @@
-/** Default per-tag style objects for the React Native preset — mirrors `styles.css`'s
- * web defaults (heading scale, link color/underline, code/blockquote treatment, list
- * spacing) so RN output looks like the web default instead of unstyled plain text. */
+/** Default per-tag style objects for the React Native preset — mirrors `styles.css`'s web defaults
+ * so RN output looks like the web default instead of unstyled plain text. */
 export const defaultReactNativeStyles = {
     p: { marginBottom: 12, lineHeight: 22 },
     h1: { fontSize: 28, fontWeight: "700", marginTop: 20, marginBottom: 10 },

package/dist/toHtml.d.ts

@@ -1,7 +1,17 @@
-/**
- * Renders raw MDX/markdown to a static HTML string — no React, no JSX component
- * evaluation. For contexts that need plain HTML (email, RSS, non-React embeds),
- * not a mounted React tree; use `compileMDX`/`MDXContent` for that instead.
- * JSX inside the source (e.g. `<Callout>`) is passed through as literal HTML tags.
- */
-export declare function toHtml(source: string): Promise<string>;
+/** Renders a custom JSX tag to an HTML string. `props` values are always strings (HTML parsing,
+ * not JSX). `childrenHtml` is the tag's contents, already rendered, nested tags resolved first. */
+export type ToHtmlComponent = (props: Record<string, string>, childrenHtml: string) => string;
+export interface ToHtmlOptions {
+    /** Renders custom tags (e.g. `<Callout>`, `<EntryLink id>`) by tag name, case-insensitive.
+     * `EntryLink` defaults to `<a href="/entries/{id}">` unless overridden. */
+    components?: Record<string, ToHtmlComponent>;
+    /** Adds `target`/`rel` to links whose `href` has a URL scheme (`https:`, `mailto:`, ...).
+     * `true` uses `target="_blank" rel="noopener noreferrer"`; pass an object to override. */
+    externalLinks?: boolean | {
+        target?: string;
+        rel?: string;
+    };
+}
+/** Renders MDX/markdown to a static HTML string — no React, no mounted tree. Use
+ * `compileMDX`/`MDXContent` instead when you need a React tree. */
+export declare function toHtml(source: string, options?: ToHtmlOptions): Promise<string>;

package/dist/toHtml.js

@@ -2,21 +2,73 @@ import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkGfm from "remark-gfm";
 import remarkRehype from "remark-rehype";
+import rehypeRaw from "rehype-raw";
 import rehypeSlug from "rehype-slug";
 import rehypeStringify from "rehype-stringify";
-/**
- * Renders raw MDX/markdown to a static HTML string — no React, no JSX component
- * evaluation. For contexts that need plain HTML (email, RSS, non-React embeds),
- * not a mounted React tree; use `compileMDX`/`MDXContent` for that instead.
- * JSX inside the source (e.g. `<Callout>`) is passed through as literal HTML tags.
- */
-export async function toHtml(source) {
-    const file = await unified()
+import { toHtml as hastToHtml } from "hast-util-to-html";
+const SCHEME_HREF = /^[a-z][a-z0-9+.-]*:/i;
+const defaultEntryLink = (props, childrenHtml) => `<a href="/entries/${props.id ?? ""}">${childrenHtml}</a>`;
+function hastPropsToStrings(properties) {
+    const props = {};
+    for (const [key, value] of Object.entries(properties ?? {})) {
+        if (typeof value === "string")
+            props[key] = value;
+        else if (Array.isArray(value))
+            props[key] = value.join(" ");
+    }
+    return props;
+}
+function rehypeDraftbase(options) {
+    const componentsByTag = options.components
+        ? new Map(Object.entries({ EntryLink: defaultEntryLink, ...options.components }).map(([name, render]) => [name.toLowerCase(), render]))
+        : undefined;
+    return (tree) => {
+        function transform(node) {
+            for (const child of node.children ?? [])
+                transform(child);
+            if (node.type !== "element" || !node.tagName)
+                return;
+            const render = componentsByTag?.get(node.tagName);
+            if (render) {
+                const childrenHtml = hastToHtml({ type: "root", children: node.children ?? [] }, {
+                    allowDangerousHtml: true,
+                });
+                node.value = render(hastPropsToStrings(node.properties), childrenHtml);
+                node.type = "raw";
+                node.tagName = undefined;
+                node.properties = undefined;
+                node.children = undefined;
+                return;
+            }
+            if (node.tagName === "a" && options.externalLinks) {
+                const href = node.properties?.href;
+                if (typeof href !== "string" || !SCHEME_HREF.test(href))
+                    return;
+                const overrides = typeof options.externalLinks === "object" ? options.externalLinks : {};
+                node.properties = {
+                    ...node.properties,
+                    target: overrides.target ?? "_blank",
+                    rel: overrides.rel ?? "noopener noreferrer",
+                };
+            }
+        }
+        transform(tree);
+    };
+}
+/** Renders MDX/markdown to a static HTML string — no React, no mounted tree. Use
+ * `compileMDX`/`MDXContent` instead when you need a React tree. */
+export async function toHtml(source, options = {}) {
+    const needsRawParse = Boolean(options.components);
+    const processor = unified()
         .use(remarkParse)
         .use(remarkGfm)
-        .use(remarkRehype, { allowDangerousHtml: true })
+        .use(remarkRehype, { allowDangerousHtml: true });
+    if (needsRawParse)
+        processor.use(rehypeRaw);
+    processor
         .use(rehypeSlug)
-        .use(rehypeStringify, { allowDangerousHtml: true })
-        .process(source);
+        .use(rehypeDraftbase, options)
+        .use(rehypeStringify, { allowDangerousHtml: true });
+    const file = await processor.process(source);
     return String(file);
 }

package/dist/toHtml.test.js

@@ -10,3 +10,43 @@ test("supports gfm tables", async () => {
     const html = await toHtml("| a | b |\n| - | - |\n| 1 | 2 |");
     assert.match(html, /<table>/);
 });
+test("leaves custom tags as literal HTML when components isn't passed", async () => {
+    const html = await toHtml('<EntryLink id="abc">Post</EntryLink><Callout>hi</Callout>');
+    assert.match(html, /<EntryLink id="abc">Post<\/EntryLink>/);
+    assert.match(html, /<Callout>hi<\/Callout>/);
+});
+test("EntryLink defaults to /entries/{id} once components is passed", async () => {
+    const html = await toHtml('<EntryLink id="abc">Post</EntryLink>', { components: {} });
+    assert.match(html, /<a href="\/entries\/abc">Post<\/a>/);
+});
+test("components renders a custom tag, keyed case-insensitively, with string props", async () => {
+    const html = await toHtml('<Callout type="warning">Careful</Callout>', {
+        components: {
+            Callout: (props, childrenHtml) => `<div class="callout-${props.type}">${childrenHtml}</div>`,
+        },
+    });
+    assert.match(html, /<div class="callout-warning">Careful<\/div>/);
+});
+test("components overrides the default EntryLink", async () => {
+    const html = await toHtml('<EntryLink id="abc">Post</EntryLink>', {
+        components: {
+            EntryLink: (props, childrenHtml) => `<a href="/blog/${props.id}">${childrenHtml}</a>`,
+        },
+    });
+    assert.match(html, /<a href="\/blog\/abc">Post<\/a>/);
+});
+test("components resolves nested custom tags before serializing the parent's children", async () => {
+    const html = await toHtml('<Callout><EntryLink id="abc">Post</EntryLink></Callout>', {
+        components: {
+            Callout: (_props, childrenHtml) => `<div>${childrenHtml}</div>`,
+        },
+    });
+    assert.match(html, /<div><a href="\/entries\/abc">Post<\/a><\/div>/);
+});
+test("adds target/rel to external links when externalLinks is true", async () => {
+    const html = await toHtml("[ext](https://example.com) and [rel](/local)", {
+        externalLinks: true,
+    });
+    assert.match(html, /<a href="https:\/\/example\.com" target="_blank" rel="noopener noreferrer">ext<\/a>/);
+    assert.match(html, /<a href="\/local">rel<\/a>/);
+});

package/dist/vue.d.ts

@@ -6,9 +6,7 @@ export interface CompiledMDX {
 }
 export type { FailedMDX };
 /**
- * Compiles raw MDX/markdown into a renderable Vue component. Vue has no RSC-style
- * async component, so call this from `setup()`/a composable and render the result
- * yourself: `h(Content, props)` or `<component :is="Content" />`. Standard markdown
- * elements render via real DOM tags with zero setup.
+ * Compiles raw MDX/markdown into a renderable Vue component. Vue has no RSC-style async component, so call this
+ * from `setup()`/a composable and render the result yourself: `h(Content, props)`.
  */
 export declare function compileMDX(source: string): Promise<CompiledMDX | FailedMDX>;

package/dist/vue.js

@@ -2,10 +2,8 @@ import { compileMDXCore, makeDefaultEntryLink } from "./core.js";
 import { vueJsxRuntime } from "./vueRuntime.js";
 const defaultComponents = { EntryLink: makeDefaultEntryLink(vueJsxRuntime) };
 /**
- * Compiles raw MDX/markdown into a renderable Vue component. Vue has no RSC-style
- * async component, so call this from `setup()`/a composable and render the result
- * yourself: `h(Content, props)` or `<component :is="Content" />`. Standard markdown
- * elements render via real DOM tags with zero setup.
+ * Compiles raw MDX/markdown into a renderable Vue component. Vue has no RSC-style async component, so call this
+ * from `setup()`/a composable and render the result yourself: `h(Content, props)`.
  */
 export async function compileMDX(source) {
     return compileMDXCore(source, vueJsxRuntime, defaultComponents);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@draftbase/renderer",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Framework-agnostic MDX renderer for Draftbase content (React, Next.js RSC, React Native, Astro, Vite, Vue)",
   "keywords": [
     "draftbase",
@@ -61,7 +61,9 @@
     "remark-gfm": "^4.0.0",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
+    "rehype-raw": "^7.0.0",
     "rehype-slug": "^6.0.0",
+    "hast-util-to-html": "^9.0.0",
     "rehype-stringify": "^10.0.1",
     "unified": "^11.0.5"
   },