From c0bd72d2c71812eaf8b9bd81f84e55c05f51609b Mon Sep 17 00:00:00 2001
From: eps1lon <sebastian.silbermann@vercel.com>
Date: Mon, 12 Aug 2024 17:14:54 +0200
Subject: [PATCH] `react-markup` reference

---
 src/content/reference/react-markup/index.md   | 16 +++++
 .../reference/react-markup/renderToMarkup.md  | 68 +++++++++++++++++++
 src/sidebarReference.json                     | 14 +++-
 3 files changed, 97 insertions(+), 1 deletion(-)
 create mode 100644 src/content/reference/react-markup/index.md
 create mode 100644 src/content/reference/react-markup/renderToMarkup.md

diff --git a/src/content/reference/react-markup/index.md b/src/content/reference/react-markup/index.md
new file mode 100644
index 000000000..2d897eb89
--- /dev/null
+++ 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):
+
+* [`renderToMarkup`](/reference/react-markup/renderToMarkup) renders a non-interactive React tree with support for Server Components but not Client Components. 
\ No newline at end of file
diff --git a/src/content/reference/react-markup/renderToMarkup.md b/src/content/reference/react-markup/renderToMarkup.md
new file mode 100644
index 000000000..0c73b644a
--- /dev/null
+++ b/src/content/reference/react-markup/renderToMarkup.md
@@ -0,0 +1,68 @@
+---
+title: renderToMarkup
+---
+
+
+<Intro>
+
+`renderToMarkup` renders a React tree to non-interactive HTML.
+
+```js
+const stream = renderToMarkup(reactNode, options?)
+```
+
+</Intro>
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `renderToMarkup(reactNode, options?)` {/*renderToMarkup*/}
+
+You can call `renderToMarkup` in a React Server environment (e.g. in a Server Action) to render a non-interactive tree of React components to HTML.
+
+```js
+import { renderToMarkup } from 'react-dom/server';
+
+const markup = await renderToMarkup(<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*/}
+
+`renderToMarkup` returns a Promise that will resolve with the HTML string of the rendered React tree.
+
+#### Caveats {/*caveats*/}
+
+* Will throw when Client Components (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 `renderToMarkup` :
+
+```js {7}
+import { renderToMarkup } 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 renderToMarkup(<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
index 50e0a3dff..f902a4088 100644
--- a/src/sidebarReference.json
+++ b/src/sidebarReference.json
@@ -390,6 +390,18 @@
         }
       ]
     },
+    {
+      "title": "react-markup",
+      "path": "/reference/react-markup",
+      "canary": true,
+      "routes": [
+        {
+          "title": "renderToMarkup",
+          "path": "/reference/react-markup/renderToMarkup",
+          "canary": true
+        }
+      ]
+    },
     {
       "hasSectionHeader": true,
       "sectionHeader": "Legacy APIs"
@@ -433,4 +445,4 @@
       ]
     }
   ]
-}
\ No newline at end of file
+}