Sarah White committed Feb 16, 2021 1 2 = Equations and Formulas :stem: asciimath Sarah White committed Feb 16, 2021 3 4 5 6 7 :url-mathjax: https://www.mathjax.org :url-asciimath: https://docs.mathjax.org/en/latest/input/asciimath.html :url-latexmath: https://docs.mathjax.org/en/latest/input/tex/index.html :url-mathjax-docs: https://meta.math.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference Sarah White committed Feb 16, 2021 8 If you need to display Science, Technology, Engineering and Math (STEM) expressions in your output, the HTML backend integrates with xref:asciidoctor:stem:mathjax.adoc[MathJax] and Docbook backend integrates with the xref:asciidoctor:stem:asciimath-gem.adoc[AsciiMath RubyGem]. Sarah White committed Feb 16, 2021 9 10 11 12 13 14 15 16 17 18 == Activating STEM support To activate equation and formula support, simply set the stem attribute in the document's header (or by passing the attribute to the command line or API). .Setting the stem attribute [source] ---- include::example$stem.adoc[tag=base-co] ---- Dan Allen committed Feb 16, 2021 19 <.> The default notation value, asciimath, is assigned implicitly. Sarah White committed Feb 16, 2021 20 21 By default, Asciidoctor's stem support assumes all equations are AsciiMath if not specified explicitly. Dan Allen committed Feb 16, 2021 22 The HTML backend supports STEM content written in {url-asciimath}[Asciimath^] and {url-latexmath}[TeX and LaTeX^] math notation. Sarah White committed Feb 16, 2021 23 The DocBook backend only supports AsciiMath notation. Sarah White committed Feb 16, 2021 24 Dan Allen committed Feb 16, 2021 25 If you want to use the LaTeX notation by default, assign latexmath to the stem attribute. Sarah White committed Feb 16, 2021 26 Dan Allen committed Feb 16, 2021 27 .Assigning an alternative notation to the stem attribute Sarah White committed Feb 16, 2021 28 29 30 31 32 [source] ---- include::example$stem.adoc[tag=base-alt] ---- Dan Allen committed Feb 16, 2021 33 34 35 TIP: You can use both notations in the same document. The value of the stem attribute merely sets the default notation. To set the notation explicitly for a given block or inline span, just use asciimath or latexmath in place of stem as explained in <>. Sarah White committed Feb 16, 2021 36 37 38 39 Stem content can be displayed inline with other content or as discrete blocks. No substitutions are applied to the content within a stem macro or block. Sarah White committed Feb 16, 2021 40 [#inline] Dan Allen committed Feb 16, 2021 41 == Inline STEM content Sarah White committed Feb 16, 2021 42 43 44 45 46 47 48 49 50 The best way to mark up an inline formula is to use the stem macro. .Inline stem macro syntax [source#ex-inline] ---- include::example$stem.adoc[tag=in-co] ---- <.> The inline stem macro contains only one colon (:). Dan Allen committed Feb 16, 2021 51 <.> Place the expression within the square brackets ([ ]) of the macro. Sarah White committed Feb 16, 2021 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 The result of <> is displayed below. ==== include::example$stem.adoc[tag=in] ==== If the inline stem equation contains a right square bracket, you must escape this character using a backslash. .Inline stem macro with a right square bracket [source#ex-square-bracket] ---- include::example$stem.adoc[tag=in-sb] ---- The result of <> is displayed below. ==== include::example$stem.adoc[tag=in-sb] ==== A stem macro is an implicit passthrough macro. That's why, despite the fact that the x expression matches the syntax of an attribute reference, you don't have to escape it. Sarah White committed Feb 16, 2021 76 [#block] Dan Allen committed Feb 16, 2021 77 == Block STEM content Sarah White committed Feb 16, 2021 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 Block formulas are marked up by assigning the stem style to a delimited passthrough block. .Delimited stem block syntax [source#ex-block] ---- include::example$stem.adoc[tag=bl-co] ---- <.> Assign the stem style to the passthrough block. <.> A passthrough block is delimited by a line of four consecutive plus signs (pass:[++++]). The result <> is rendered beautifully in the browser thanks to MathJax! include::example$stem.adoc[tag=bl] TIP: You don't need to add special delimiters around the expression as the {url-mathjax-docs}[MathJax documentation^] suggests. Asciidoctor handles that for you automatically! Dan Allen committed Feb 16, 2021 96 97 [#mixing-notations] == Mixing STEM notations Sarah White committed Feb 16, 2021 98 Dan Allen committed Feb 16, 2021 99 You can use multiple notations for STEM content within the same document by using the notation's name instead of the keyword stem. Sarah White committed Feb 16, 2021 100 Dan Allen committed Feb 16, 2021 101 For example, if you want to write an inline equation using the LaTeX notation, name the macro latexmath. Sarah White committed Feb 16, 2021 102 103 104 105 106 107 108 109 110 111 112 .Inline latexmath macro syntax [source#ex-latexmath] ---- include::example$stem.adoc[tag=multi-l] ---- The result of <> is displayed below. include::example$stem.adoc[tag=multi-l] Dan Allen committed Feb 16, 2021 113 The name that maps to the notation you want to use can also be applied to block STEM content. Sarah White committed Feb 16, 2021 114 115 116 117 118 119 .Delimited asciimath block syntax [source] ---- include::example\$stem.adoc[tag=multi-a] ----