reactjs · eps1lon · Aug 12, 2024 · Aug 14, 2024 · Aug 14, 2024
diff --git a/src/content/reference/react-markup/index.md b/src/content/reference/react-markup/index.md
@@ -0,0 +1,16 @@
+---
+title: React Markup APIs
+---
+
+<Intro>
+
+The `react-markup` package provides the ability to render standalone HTML from Server Components for use in embedded contexts such as e-mails and RSS/Atom feeds. 
+It cannot use Client Components and does not hydrate. It is intended to be paired with the generic React package, which is shipped as `react` to npm.
+
+</Intro>
+
+## APIs {/*apis*/}
+
+These APIs can be imported from the React Server environment (e.g. in Server Actions):
+
+* [`renderToHTML`](/reference/react-markup/renderToHTML) renders a non-interactive React tree with support for Server Components but not Client Components. 
diff --git a/src/content/reference/react-markup/renderToHTML.md b/src/content/reference/react-markup/renderToHTML.md
@@ -0,0 +1,74 @@
+---
+title: renderToHTML
+canary: true
+---
+
+
+<Intro>
+
+`renderToHTML` renders a React tree to non-interactive HTML.
+
+```js
+const stream = renderToHTML(reactNode, options?)
+```
+
+</Intro>
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `renderToHTML(reactNode, options?)` {/*rendertohtml*/}
+
+You can call `renderToHTML` to render a non-interactive tree of React components to HTML.
+By default, it supports shared components and built-in components.
+Server Components are only allowed if used in a React Server environment (e.g. in Server Actions).
+You can also use it during Client-Side Rendering but only without Server Components.
+
+When a `<html>` tag is rendered, `renderToHTML` will automatically add `<!DOCTYPE html>` doctype.
+
+```js
+import { experimental_renderToHTML as renderToHTML } from 'react-markup';
+
+const markup = await renderToHTML(<App />);
+```
+
+#### Parameters {/*parameters*/}
+
+* `reactNode`: A React node you want to render to HTML. For example, a JSX element like `<App />`.
+
+* **optional** `options`: An object for server render.
+  * **optional** `identifierPrefix`: A string prefix React uses for IDs generated by [`useId`.](/reference/react/useId) Useful to avoid conflicts when the markup is embedded in or combined with other markup that is rendered by React.  
+  * **optional** `onError`: A callback that fires whenever there is a server error. By default, this only calls `console.error`. If you override it to [log crash reports,](#logging-crashes-on-the-server) make sure that you still call `console.error`. This is different to the rejection reason of the created Promise since it'll include the parent component stack.
+  * **optional** `signal`: An [abort signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that lets you [abort rendering](#aborting-server-rendering). The original Promise will reject.
+
+#### Returns {/*returns*/}
+
+`renderToHTML` returns a Promise that will resolve with the HTML string of the rendered React tree.
+
+#### Caveats {/*caveats*/}
+
+* Will throw when Client APIs (e.g. `useState` or `useEffect`) are used.
+
+---
+
+## Usage {/*usage*/}
+
+### Rendering a React tree as an Email {/*rendering-a-react-tree-as-an-email*/}
+
+Await the call of `renderToHTML` :
+
+```js {7}
+import { experimental_renderToHTML as renderToHTML } from 'react-markup';
+import EmailTemplate from './my-email-template-component.js'
+
+async function action(email, name) {
+  "use server";
+  // ... in your server, e.g. a Server Action...
+  const htmlString = await renderToHTML(<EmailTemplate name={name} />);
+  // ... send e-mail using some e-mail provider
+  await sendEmail({ to: email, contentType: 'text/html', body: htmlString });
+}
+```
diff --git a/src/sidebarReference.json b/src/sidebarReference.json
@@ -390,6 +390,18 @@
         }
       ]
     },
+    {
+      "title": "react-markup",
+      "path": "/reference/react-markup",
+      "canary": true,
+      "routes": [
+        {
+          "title": "renderToHTML",
+          "path": "/reference/react-markup/renderToHTML",
+          "canary": true
+        }
+      ]
+    },
     {
       "hasSectionHeader": true,
       "sectionHeader": "Legacy APIs"
@@ -433,4 +445,4 @@
       ]
     }
   ]
-}
+}