SOLR-14646: Add STEM notation support for the Ref Guide

solr/solr-ref-guide/src/_config.yml.template

@@ -95,3 +95,4 @@ asciidoctor:
     icons: "font"
     source-highlighter: "rouge"
     rouge-theme: "thankful-eyes"
+    stem:

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>

solr/solr-ref-guide/src/_layouts/default.html

@@ -57,5 +57,7 @@
 
 <script src="{{ "js/customscripts.js" }}"></script>
 
+{% include mathjax-support.html %}
+
 </body>
 </html>

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