Documentation: add notes on mathjax support

Signed-off-by: James Knight <[email protected]>

doc/configuration.rst

@@ -2004,6 +2004,7 @@ Advanced processing configuration
 
     See also:
 
+    - :lref:`confluence_mathjax`
     - :ref:`LaTeX directives <latex-directives>`
     - :ref:`LaTeX roles <latex-roles>`
     - :doc:`guide-math`
@@ -2022,6 +2023,42 @@ Advanced processing configuration
 
         confluence_link_suffix = '.conf'
 
+.. _confluence_mathjax:
+
+.. confval:: confluence_mathjax
+
+    .. important::
+
+        This option relies on additional configuration of a Confluence
+        instance or additional directives such as using an HTML macro.
+        Both of these approaches may not be available in a default
+        Confluence configuration. Confluence Cloud may require a custom
+        marketplace add-on. Confluence Data Center can require a system
+        administrator configuring site support for MathJax; or environments
+        that have a Confluence HTML macro enabled, users can attempt to
+        include MathJax library support via the use of a
+        :lref:`confluence_html` directive.
+
+        While this extension aims to support the capability of generating
+        raw content that MathJax could render, the complete solution of
+        using MathJax on a Confluence instance is considered unsupported.
+
+    Generate math content into a raw format that can be rendered on a
+    Confluence instance that has been configured to support `MathJax`_.
+
+    .. code-block:: python
+
+        confluence_mathjax = True
+
+    See also:
+
+    - :lref:`confluence_latex_macro`
+    - :ref:`LaTeX directives <latex-directives>`
+    - :ref:`LaTeX roles <latex-roles>`
+    - :doc:`guide-math`
+
+    .. versionadded:: 2.10
+
 .. index:: Mentions; Configuration
 
 .. _confluence_mentions:
@@ -2153,7 +2190,7 @@ Third-party related options
     .. warning::
 
         This option relies on an HTML macro which is not available in a
-        default  Confluence configuration. Using this option is only useful
+        default Confluence configuration. Using this option is only useful
         for users that have instances where a system administrator has
         enabled their use.
 
@@ -2290,6 +2327,7 @@ Deprecated options
 .. _Confluence editor: https://support.atlassian.com/confluence-cloud/docs/confluence-cloud-editor-roadmap/
 .. _Confluence-supported syntax highlight languages: https://confluence.atlassian.com/confcloud/code-block-macro-724765175.html
 .. _Key of the space: https://support.atlassian.com/confluence-cloud/docs/choose-a-space-key/
+.. _MathJax: https://www.mathjax.org/
 .. _Pygments documented language types: http://pygments.org/docs/lexers/
 .. _Requests -- Authentication: https://requests.readthedocs.io/en/stable/user/authentication/
 .. _Requests SSL Cert Verification: https://requests.readthedocs.io/en/stable/user/advanced/#ssl-cert-verification

doc/guide-math.rst

@@ -3,6 +3,7 @@
 Math support
 ============
 
+.. versionchanged:: 2.10 Limited support for generating MathJax-raw content.
 .. versionchanged:: 1.8 Support for using Confluence-supported LaTeX macros.
 .. versionchanged:: 1.7 SVG-generated math images requires the
                          ``sphinx.ext.imgmath`` extension to be explicitly
@@ -192,7 +193,50 @@ determine the name of the macro by:
         ...
       </ac:structured-macro>
 
+.. index:: Math; MathJax
+
+MathJax integration
+-------------------
+
+.. important::
+
+    While this extension aims to support the capability of generating raw
+    content that MathJax could render, the complete solution of using
+    MathJax on a Confluence instance is considered unsupported.
+
+Stock Confluence instances do not include support to render `MathJax`_
+content. However, if the instance has been configured to support the
+JavaScript engine, the Confluence builder extension can be configured to
+generate output that is compatible with MathJax.
+
+Users can use the :lref:`confluence_mathjax` option to output all math
+content into a MathJax-compatible format:
+
+.. code-block:: python
+
+    confluence_mathjax = True
+
+There are no system administrator guidelines on how to setup a Confluence
+instance to provide MathJax support.
+
+Users on a Confluence Data Center instance that has enabled support for
+HTML macros may be able to use the :lref:`confluence_html` directive to
+enable MathJax support on their pages. For example, adding the following
+into a project's ``conf.py``:
+
+.. code-block:: rst
+
+    rst_prolog = """
+
+    .. confluence_html::
+
+        <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
+
+    """
+
+User experience may vary.
 
 .. references ------------------------------------------------------------------
 
+.. _MathJax: https://www.mathjax.org/
 .. _sphinx.ext.imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath