diff --git a/packages/lib/services/plugins/api/types.ts b/packages/lib/services/plugins/api/types.ts
index be5519398c..ed4678c5ba 100644
--- a/packages/lib/services/plugins/api/types.ts
+++ b/packages/lib/services/plugins/api/types.ts
@@ -612,6 +612,45 @@ export enum ContentScriptType {
 	 *   plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
 	 *   to see how the data should be structured.
 	 *
+	 * ## Supporting the Rich Text Editor
+	 *
+	 * Joplin's Rich Text Editor works with rendered HTML, which is converted back
+	 * to markdown when saving. To prevent the original markdown for your plugin from
+	 * being lost, Joplin needs additional metadata.
+	 *
+	 * To provide this,
+	 * 1. Wrap the HTML generated by your plugin in an element with class `joplin-editable`.
+	 *    For example,
+	 *    ```html
+	 *    <div class="joplin-editable">
+	 *        ...your html...
+	 *    </div>
+	 *    ```
+	 * 2. Add a child with class `joplin-source` that contains the original markdown that
+	 *    was rendered by your plugin. Include `data-joplin-source-open`, `data-joplin-source-close`,
+	 *    and `data-joplin-language` attributes.
+	 *    For example, if your plugin rendered the following code block,
+	 *    ````
+	 *    ```foo
+	 *    ... original source here ...
+	 *    ```
+	 *    ````
+	 *    then it should render to
+	 *    ```html
+	 *    <div class="joplin-editable">
+	 *        <pre
+	 *            class="joplin-source"
+	 *            data-joplin-language="foo"
+	 *            data-joplin-source-open="```foo&NewLine;"
+	 *            data-joplin-source-close="```"
+	 *        > ... original source here ... </pre>
+	 *        ... rendered HTML here ...
+	 *    </div>
+	 *    ```
+	 *
+	 * See [the demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
+	 * for a complete example.
+	 *
 	 * ## Getting the settings from the renderer
 	 *
 	 * You can access your plugin settings from the renderer by calling