From c57a54bba54a6bae52255a56db945342b6b29fba Mon Sep 17 00:00:00 2001
From: Cassandra Targett <cassandra.targett@lucidworks.com>
Date: Mon, 13 Jul 2020 16:56:11 -0500
Subject: [PATCH] SOLR-14646: Add STEM notation support for the Ref Guide

---
 solr/solr-ref-guide/src/_config.yml.template  |  1 +
 .../src/_includes/mathjax-support.html        | 22 +++++++++
 solr/solr-ref-guide/src/_layouts/default.html |  2 +
 .../src/meta-docs/asciidoc-syntax.adoc        | 45 +++++++++++++++++++
 4 files changed, 70 insertions(+)
 create mode 100644 solr/solr-ref-guide/src/_includes/mathjax-support.html

diff --git a/solr/solr-ref-guide/src/_config.yml.template b/solr/solr-ref-guide/src/_config.yml.template
index 4d91c84986a..36c92edc35e 100755
--- a/solr/solr-ref-guide/src/_config.yml.template
+++ b/solr/solr-ref-guide/src/_config.yml.template
@@ -95,3 +95,4 @@ asciidoctor:
     icons: "font"
     source-highlighter: "rouge"
     rouge-theme: "thankful-eyes"
+    stem:
diff --git a/solr/solr-ref-guide/src/_includes/mathjax-support.html b/solr/solr-ref-guide/src/_includes/mathjax-support.html
new file mode 100644
index 00000000000..8d812b5e393
--- /dev/null
+++ b/solr/solr-ref-guide/src/_includes/mathjax-support.html
@@ -0,0 +1,22 @@
+{% comment %}This adds MathJax support for rendering math formulae and equations in HTML.{% endcomment %}
+
+<script type="text/x-mathjax-config">
+MathJax.Hub.Config({
+  messageStyle: "none",
+  tex2jax: {
+    inlineMath: [["\\(","\\)"]],
+    displayMath: [["\\[","\\]"]],
+    ignoreClass: "nostem|nolatexmath"
+  },
+  asciimath2jax: {
+    delimiters: [["\\$","\\$"]],
+    ignoreClass: "nostem|noasciimath"
+  },
+  TeX: {
+      equationNumbers: {
+        autoNumber: "none"
+      }
+    }
+});
+</script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML-AM_HTMLorMML"></script>
diff --git a/solr/solr-ref-guide/src/_layouts/default.html b/solr/solr-ref-guide/src/_layouts/default.html
index 37c7173fe09..5b929bc2e0e 100755
--- a/solr/solr-ref-guide/src/_layouts/default.html
+++ b/solr/solr-ref-guide/src/_layouts/default.html
@@ -57,5 +57,7 @@
 
 <script src="{{ "js/customscripts.js" }}"></script>
 
+{% include mathjax-support.html %}
+
 </body>
 </html>
diff --git a/solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc b/solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc
index 3bacab644b1..87cf318cb4a 100644
--- a/solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc
+++ b/solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc
@@ -380,3 +380,48 @@ Text of note
 In this example, the type of admonition is included in square brackets (`[NOTE]`), and the title is prefixed with a period. Four equal signs give the start and end points of the note text (which can include new lines, lists, code examples, etc.).
 
 More info: http://asciidoctor.org/docs/user-manual/#admonition
+
+== STEM Notation Support
+
+We have set up the Ref Guide to be able to support STEM notation whenever it's needed.
+
+The http://asciimath.org/[AsciiMath] syntax is supported by default, but LaTeX syntax is also available.
+
+To insert a mathematical formula inline with your text, you can simply write:
+
+[source]
+----
+stem:[a//b]
+----
+
+MathJax.js will render the formula as proper mathematical notation when a user loads the page.
+When the above example is converted to HTML, it will look like this to a user: stem:[a//b]
+
+To insert LaTeX, preface the formula with `latexmath` instead of `stem`:
+
+[source]
+----
+latexmath:[tp \leq 1 - (1 - sim^{rows})^{bands}]
+----
+
+Long formulas, or formulas which should to be set off from the main text, can use the block syntax prefaced by `stem` or `latexmath`:
+
+[source]
+----
+[stem]
+++++
+sqrt(3x-1)+(1+x)^2 < y
+++++
+----
+
+or for LaTeX:
+
+[source]
+----
+[latexmath]
+++++
+[tp \leq 1 - (1 - sim^{rows})^{bands}]
+++++
+----
+
+More info: https://asciidoctor.org/docs/user-manual/#stem-in