[lucene-solr] branch branch_8x updated: SOLR-14646: Add STEM notation support for the Ref Guide

[ct...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ctargett pushed a commit to branch branch_8x
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git


The following commit(s) were added to refs/heads/branch_8x by this push:
     new b214d90  SOLR-14646: Add STEM notation support for the Ref Guide
b214d90 is described below

commit b214d90209d5870f2d65b3ae2c2a9568651413a5
Author: Cassandra Targett <ca...@lucidworks.com>
AuthorDate: Mon Jul 13 16:56:11 2020 -0500

    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(+)

diff --git a/solr/solr-ref-guide/src/_config.yml.template b/solr/solr-ref-guide/src/_config.yml.template
index 4d91c84..36c92ed 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 0000000..8d812b5
--- /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 37c7173..5b929bc 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 3bacab6..87cf318 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