Merge pull request #1022 from edemaine/buildhtml

Add buildHTMLTree

katex.js

@@ -11,7 +11,7 @@
 import ParseError from "./src/ParseError";
 import Settings from "./src/Settings";
 
-import buildTree from "./src/buildTree";
+import { buildTree, buildHTMLTree } from "./src/buildTree";
 import parseTree from "./src/parseTree";
 import utils from "./src/utils";
 
@@ -28,7 +28,7 @@ let render = function(
     options: SettingsOptions,
 ) {
     utils.clearNode(baseNode);
-    const node = generateBuildTree(expression, options).toNode();
+    const node = renderToDomTree(expression, options).toNode();
     baseNode.appendChild(node);
 };
 
@@ -53,7 +53,7 @@ const renderToString = function(
     expression: string,
     options: SettingsOptions,
 ): string {
-    const markup = generateBuildTree(expression, options).toMarkup();
+    const markup = renderToDomTree(expression, options).toMarkup();
     return markup;
 };
 
@@ -73,7 +73,7 @@ const generateParseTree = function(
  * Generates and returns the katex build tree. This is used for advanced
  * use cases (like rendering to custom output).
  */
-const generateBuildTree = function(
+const renderToDomTree = function(
     expression: string,
     options: SettingsOptions,
 ) {
@@ -82,20 +82,59 @@ const generateBuildTree = function(
     return buildTree(tree, expression, settings);
 };
 
+/**
+ * Generates and returns the katex build tree, with just HTML (no MathML).
+ * This is used for advanced use cases (like rendering to custom output).
+ */
+const renderToHTMLTree = function(
+    expression: string,
+    options: SettingsOptions,
+) {
+    const settings = new Settings(options);
+    const tree = parseTree(expression, settings);
+    return buildHTMLTree(tree, expression, settings);
+};
+
 module.exports = {
+    /**
+     * Renders the given LaTeX into an HTML+MathML combination, and adds
+     * it as a child to the specified DOM node.
+     */
     render,
+    /**
+     * Renders the given LaTeX into an HTML+MathML combination string,
+     * for sending to the client.
+     */
     renderToString,
     /**
+     * KaTeX error, usually during parsing.
+     */
+    ParseError,
+    /**
+     * Parses the given LaTeX into KaTeX's internal parse tree structure,
+     * without rendering to HTML or MathML.
+     *
      * NOTE: This method is not currently recommended for public use.
      * The internal tree representation is unstable and is very likely
      * to change. Use at your own risk.
      */
     __parse: generateParseTree,
     /**
+     * Renders the given LaTeX into an HTML+MathML internal DOM tree
+     * representation, without flattening that representation to a string.
+     *
      * NOTE: This method is not currently recommended for public use.
      * The internal tree representation is unstable and is very likely
      * to change. Use at your own risk.
      */
-    __getBuildTree: generateBuildTree,
-    ParseError,
+    __renderToDomTree: renderToDomTree,
+    /**
+     * Renders the given LaTeX into an HTML internal DOM tree representation,
+     * without MathML and without flattening that representation to a string.
+     *
+     * NOTE: This method is not currently recommended for public use.
+     * The internal tree representation is unstable and is very likely
+     * to change. Use at your own risk.
+     */
+    __renderToHTMLTree: renderToHTMLTree,
 };

src/buildTree.js

@@ -9,24 +9,19 @@ import Style from "./Style";
 import type ParseNode from "./ParseNode";
 import type domTree from "./domTree";
 
-const buildTree = function(
+const optionsFromSettings = function(settings: Settings) {
+    return new Options({
+        style: (settings.displayMode ? Style.DISPLAY : Style.TEXT),
+        maxSize: settings.maxSize,
+    });
+};
+
+export const buildTree = function(
     tree: ParseNode[],
     expression: string,
     settings: Settings,
 ): domTree.span {
-    settings = settings || new Settings({});
-
-    let startStyle = Style.TEXT;
-    if (settings.displayMode) {
-        startStyle = Style.DISPLAY;
-    }
-
-    // Setup the default options
-    const options = new Options({
-        style: startStyle,
-        maxSize: settings.maxSize,
-    });
-
+    const options = optionsFromSettings(settings);
     // `buildHTML` sometimes messes with the parse tree (like turning bins ->
     // ords), so we build the MathML version first.
     const mathMLNode = buildMathML(tree, expression, options);
@@ -43,4 +38,19 @@ const buildTree = function(
     }
 };
 
+export const buildHTMLTree = function(
+    tree: ParseNode[],
+    expression: string,
+    settings: Settings,
+): domTree.span {
+    const options = optionsFromSettings(settings);
+    const htmlNode = buildHTML(tree, options);
+    const katexNode = buildCommon.makeSpan(["katex"], [htmlNode]);
+    if (settings.displayMode) {
+        return buildCommon.makeSpan(["katex-display"], [katexNode]);
+    } else {
+        return katexNode;
+    }
+};
+
 export default buildTree;