fix(#4140): Deprecate mermaidAPI.render

mermaid-js · Feb 24, 2023 · 0206ff5 · 0206ff5
1 parent 1e5d9ae
commit 0206ff5
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 24 deletions.
diff --git a/docs/config/setup/modules/mermaidAPI.md b/docs/config/setup/modules/mermaidAPI.md
@@ -95,7 +95,7 @@ mermaid.initialize(config);
 
 #### Defined in
 
-[mermaidAPI.ts:680](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L680)
+[mermaidAPI.ts:659](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L659)
 
 ## Functions
 

diff --git a/packages/mermaid/src/mermaid.ts b/packages/mermaid/src/mermaid.ts
@@ -337,6 +337,32 @@ const parse = async (text: string, parseOptions?: ParseOptions): Promise<boolean
   });
 };
 
+/**
+ * Function that renders an svg with a graph from a chart definition. Usage example below.
+ *
+ * ```javascript
+ * mermaid.initialize({
+ *   startOnLoad: true,
+ * });
+ * $(function () {
+ *   const graphDefinition = 'graph TB\na-->b';
+ *   const cb = function (svgGraph) {
+ *     console.log(svgGraph);
+ *   };
+ *   mermaid.render('id1', graphDefinition, cb);
+ * });
+ * ```
+ *
+ * @param id - The id for the SVG element (the element to be rendered)
+ * @param text - The text for the graph definition
+ * @param cb - Callback which is called after rendering is finished with the svg code as in param.
+ * @param svgContainingElement - HTML element where the svg will be inserted. (Is usually element with the .mermaid class)
+ *   If no svgContainingElement is provided then the SVG element will be appended to the body.
+ *    Selector to element in which a div with the graph temporarily will be
+ *   inserted. If one is provided a hidden div will be inserted in the body of the page instead. The
+ *   element will be removed when rendering is completed.
+ * @returns Returns the rendered element as a string containing the SVG definition.
+ */
 const render = (id: string, text: string, container?: Element): Promise<RenderResult> => {
   return new Promise((resolve, reject) => {
     // This promise will resolve when the mermaidAPI.render call is done.

diff --git a/packages/mermaid/src/mermaidAPI.ts b/packages/mermaid/src/mermaidAPI.ts
@@ -370,30 +370,9 @@ export const removeExistingElements = (
 };
 
 /**
- * Function that renders an svg with a graph from a chart definition. Usage example below.
+ * @deprecated - use the `mermaid.render` function instead of `mermaid.mermaidAPI.render`
  *
- * ```javascript
- * mermaidAPI.initialize({
- *   startOnLoad: true,
- * });
- * $(function () {
- *   const graphDefinition = 'graph TB\na-->b';
- *   const cb = function (svgGraph) {
- *     console.log(svgGraph);
- *   };
- *   mermaidAPI.render('id1', graphDefinition, cb);
- * });
- * ```
- *
- * @param id - The id for the SVG element (the element to be rendered)
- * @param text - The text for the graph definition
- * @param cb - Callback which is called after rendering is finished with the svg code as in param.
- * @param svgContainingElement - HTML element where the svg will be inserted. (Is usually element with the .mermaid class)
- *   If no svgContainingElement is provided then the SVG element will be appended to the body.
- *    Selector to element in which a div with the graph temporarily will be
- *   inserted. If one is provided a hidden div will be inserted in the body of the page instead. The
- *   element will be removed when rendering is completed.
- * @returns Returns the rendered element as a string containing the SVG definition.
+ * Deprecated for external use.
  */
 
 const render = async function (