DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:mathjax

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
plugin:mathjax [2017-08-29 08:20] – for delet in the badextensions list 2a01:e35:2e29:c0c0:8ea9:82ff:fe85:2626plugin:mathjax [2024-02-13 04:53] (current) – Mark compatible with Kaos release liffiton
Line 6: Line 6:
 email      : liffiton@gmail.com email      : liffiton@gmail.com
 type       : action, syntax type       : action, syntax
-lastupdate : 2017-05-28 +lastupdate : 2021-11-20 
-compatible : Frusterick Manners, Ponder Stibbons, Rincewind, Angua, Adora Belle, Weatherwax, Binky, 2014-09-29 "Hrun", Detritus, Elenor of Tsort+compatible :  Ponder Stibbons, Rincewind, Angua, Adora Belle, Weatherwax, Binky, Hrun, Detritus, Elenor of Tsort, Frusterick Manners, Greebo, Hogfather, Igor, Jack Jackrum, Kaos
 depends    :  depends    : 
 conflicts  : creole, indexmenu2, revealjs, s5 conflicts  : creole, indexmenu2, revealjs, s5
Line 18: Line 18:
 donationurl:  donationurl: 
 ---- ----
- 
-===== Important Note - March, 2017 ===== 
- 
-Until March 31, 2017, this plugin was using the MathJax CDN for loading MathJax.  MathJax has [[https://www.mathjax.org/cdn-shutting-down/|shut down]] its CDN as of April 30, 2017. 
- 
-The default URL from which the plugin loads MathJax has been changed to use CDNJS as the MathJax maintainers recommend. If you have not changed the URL in your configuration, just update the plugin to its latest version, and your wiki should start using the new URL automatically. If you **have** modified the URL and are still using the MathJax CDN, you will need to update it in the wiki configuration manager (e.g. following the recommendation in the [[https://www.mathjax.org/cdn-shutting-down/|shutdown notice]]). And if you are not using the MathJax CDN, this should not affect you. 
  
 ===== Overview ===== ===== Overview =====
  
 This plugin adds [[http://www.mathjax.org/|MathJax]] to your wiki pages to let you easily write mathematical formulas that will be typeset and displayed cleanly.  It is written to be as simple as possible; it loads and configures the script, protects TeX math expressions from other parsing, and no more. This plugin adds [[http://www.mathjax.org/|MathJax]] to your wiki pages to let you easily write mathematical formulas that will be typeset and displayed cleanly.  It is written to be as simple as possible; it loads and configures the script, protects TeX math expressions from other parsing, and no more.
 +
 +It has been tested with MathJax version 2.7.x, the default MathJax version loaded by the plugin is 2.7.x, and all of the links to documentation here point to the v2.7 documentation.  The plugin //does not// work with MathJax v3.x without modifications ([[https://github.com/liffiton/dokuwiki-plugin-mathjax/issues/37|work in progress]]).
  
 ===== Installation ===== ===== Installation =====
  
-Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually. +Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
- +
-==== Workaround for IE and Old Dokuwiki Versions ==== +
- +
-Dokuwiki versions 2012-01-25 'Angua' and earlier have a bug that prevents this plugin from working when using Internet Explorer.  [[bug>2563|The bug]] has been fixed and shouldn't be a problem in later releases, but 2012-01-25 and before need the following workaround applied for math to render in IE: +
- +
- Edit ''inc/template.php'' and change lines 375-377 (assuming the 2012-01-25 "Angua" release) in ''_tpl_metaheaders_action()'' to: +
- +
-  $attr['_data'] = "/*<![CDATA[*/\n"+
-      $attr['_data']. +
-      "\n/*!]]>*/";+
  
 ===== Examples/Usage ===== ===== Examples/Usage =====
Line 89: Line 75:
 Additionally, you can configure MathJax via commands given in a configuration string and/or loaded from files; both methods can be controlled in the Configuration Manager.  Note that the default URL loads a reasonable configuration from the CDN, and the default configuration string modifies it slightly. Additionally, you can configure MathJax via commands given in a configuration string and/or loaded from files; both methods can be controlled in the Configuration Manager.  Note that the default URL loads a reasonable configuration from the CDN, and the default configuration string modifies it slightly.
  
-Some [[http://docs.mathjax.org/en/latest/options/ThirdParty.html|third-party MathJax extensions]] may require a different configuration than the plugin's default to operate properly.  For example, it has been reported that the XyJax extension does not function with the "CHTML" renderer.  In that case, changing the MathJax URL to ''%%//%%cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML'' (changing the 'config' parameter from the default) allows XyJax to work.+For more information on configuring MathJax, see [[https://docs.mathjax.org/en/v2.7-latest/config-files.html|Common Configurations]] and [[https://docs.mathjax.org/en/v2.7-latest/options/index.html|MathJax Configuration Options]] in the [[https://docs.mathjax.org/en/v2.7-latest/|MathJax documentation]].
  
-For more information on configuring MathJax, see [[http://docs.mathjax.org/en/latest/config-files.html|Common Configurations]] and [[http://docs.mathjax.org/en/latest/options/index.html|MathJax Configuration Options]] in the [[http://docs.mathjax.org/en/latest/|MathJax documentation]].+==== Third-Party Extensions ==== 
 + 
 +Some [[https://docs.mathjax.org/en/v2.7-latest/options/ThirdParty.html|third-party MathJax extensions]] may require a different configuration than the plugin's default to operate properly.  For example, it has been reported that the XyJax extension does not function with the "CHTML" renderer.  In that case, set the Dokuwiki configuration option ''plugin»mathjax»url'' to ''%%https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js?config=TeX-AMS_HTML.js%%'' (changing it to use the ''Tex-AMS_HTML'' MathJax configuration rather than ''TeX-AMS_CHTML'') to allow XyJax to work.
  
 ==== AsciiMath ==== ==== AsciiMath ====
  
-MathJax has the ability to parse and render [[http://asciimath.org/|AsciiMath]] markup, but it is not enabled in the default configuration of this plugin.  One easy way to enable the AsciiMath preprocessor is to use a different [[http://docs.mathjax.org/en/latest/config-files.html|configuration file]]: set ''plugin»mathjax»url'' to ''%%//%%cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML'' (That configuration enables both TeX and AsciiMath; see the list of configuration files for other options. You may want to modify some [[https://mathjax.readthedocs.org/en/latest/options/asciimath2jax.html#configure-asciimath2jax|AsciiMath-specific settings]] as well.+MathJax has the ability to parse and render [[http://asciimath.org/|AsciiMath]] markup, but it is not enabled in the default configuration of this plugin.  One easy way to enable the AsciiMath preprocessor is to use a different [[http://docs.mathjax.org/en/v2.7-latest/config-files.html|configuration file]]: set ''plugin»mathjax»url'' to ''%%https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js?config=AM_CHTML.js%%''. 
 + 
 +If you want to use AsciiMath, you should also enable the "asciimath" configuration option (in the MathJax section of your wiki'configuration manager).
  
 ==== Automatic Equation Numbering ==== ==== Automatic Equation Numbering ====
  
-MathJax 2.0 introduces [[http://docs.mathjax.org/en/latest/tex.html#automatic-equation-numbering|automatic equation numbering]], but it is not enabled in the default configuration.  To enable it, go to your wiki's configuration editor and change the ''plugin»mathjax»config'' setting to something like this:+MathJax 2.0 introduces [[https://docs.mathjax.org/en/v2.7-latest/tex.html#automatic-equation-numbering|automatic equation numbering]], but it is not enabled in the default configuration.  To enable it, go to your wiki's configuration editor and change the ''plugin»mathjax»config'' setting to something like this:
  
   MathJax.Hub.Config({   MathJax.Hub.Config({
Line 112: Line 102:
 The line ''TeX: { equationNumbers: {autoNumber: "AMS"} }'' enables the equation numbering. The line ''TeX: { equationNumbers: {autoNumber: "AMS"} }'' enables the equation numbering.
  
-See the [[http://docs.mathjax.org/en/latest/tex.html#automatic-equation-numbering|MathJax documentation]] or the [[http://cdn.mathjax.org/mathjax/latest/test/examples.html|MathJax examples page]] for the syntax for creating automatic references to equations, as well.+See the [[http://docs.mathjax.org/en/v2.7-latest/tex.html#automatic-equation-numbering|MathJax documentation]] or the [[https://cdn.rawgit.com/mathjax/MathJax/2.7.9/test/examples.html|MathJax examples page]] for the syntax for creating automatic references to equations, as well.
  
 ==== Changing default size or scale ==== ==== Changing default size or scale ====
Line 135: Line 125:
  
 Alternatively, feel free to report issues in the Discussion section below. Alternatively, feel free to report issues in the Discussion section below.
 +
 +
 +===== Notes on Older Versions =====
 +
 +==== Workaround for IE and Old Dokuwiki Versions ====
 +
 +Dokuwiki versions 2012-01-25 'Angua' and earlier have a bug that prevents this plugin from working when using Internet Explorer.  [[bug>2563|The bug]] has been fixed and shouldn't be a problem in later releases, but 2012-01-25 and before need the following workaround applied for math to render in IE:
 +
 + Edit ''inc/template.php'' and change lines 375-377 (assuming the 2012-01-25 "Angua" release) in ''_tpl_metaheaders_action()'' to:
 +
 +  $attr['_data'] = "/*<![CDATA[*/\n".
 +      $attr['_data'].
 +      "\n/*!]]>*/";
 +
 +
 +==== CDN Update - March, 2017 ====
 +
 +Until March 31, 2017, this plugin was using the MathJax CDN for loading MathJax.  MathJax has [[https://www.mathjax.org/cdn-shutting-down/|shut down]] its CDN as of April 30, 2017.
 +
 +The default URL from which the plugin loads MathJax has been changed to use CDNJS as the MathJax maintainers recommend. If you have not changed the URL in your configuration, just update the plugin to its latest version, and your wiki should start using the new URL automatically. If you **have** modified the URL and are still using the MathJax CDN, you will need to update it in the wiki configuration manager (e.g. following the recommendation in the [[https://www.mathjax.org/cdn-shutting-down/|shutdown notice]]). And if you are not using the MathJax CDN, this should not affect you.
 +
  
 ===== FAQ ===== ===== FAQ =====
Line 198: Line 209:
 :?: Are ''\newcommand'' and other custom macro/environment definitions supported? :?: Are ''\newcommand'' and other custom macro/environment definitions supported?
  
-**Answer**: [[http://docs.mathjax.org/en/latest/tex.html#defining-tex-macros|Yes]], either in your page inside math delimiters or through the configuration script.+**Answer**: [[http://docs.mathjax.org/en/v2.7-latest/tex.html#defining-tex-macros|Yes]], either in your page inside math delimiters or through the configuration script.
  
 ---- ----
Line 231: Line 242:
      
 (taken from the [[https://docs.mathjax.org/en/v2.5-latest/tex.html#tex-macros|mathjax docu]]) (taken from the [[https://docs.mathjax.org/en/v2.5-latest/tex.html#tex-macros|mathjax docu]])
 +
 +----
 +
 +:?: How to configure the MathJax plugin step by step so that we can use XyJax in DokuWiki? 
 +
 +The section on third-party extensions that mentions XyJax has been updated to correct the URL for the new CDN.  For instructions on installing/using XyJax, there's [[https://github.com/sonoisa/XyJax|the XyJax README]].  It will involve modifying and hosting the XyJax javascript file yourself (it isn't available on a CDN as far as I can tell), which is outside of the scope of this plugin.
 +
 +(Here are the steps of installation/configuration: a) Change the value of ''plugin>>mathjax>>url'' according to the Section of Third-Party Extensions. b) Follow the five steps of Installation Method 1 at [[https://github.com/sonoisa/XyJax|the XyJax README]]. For details, see https://forum.dokuwiki.org/thread/12374)
 +
 +----
 +
  
 ===== Discussion ===== ===== Discussion =====
Line 242: Line 264:
  
 > **Printing** (via the browser ''File > Print'') yields **overlap** between inline Mathjax content and the normal non-Mathjax text that follows. --- Johan > **Printing** (via the browser ''File > Print'') yields **overlap** between inline Mathjax content and the normal non-Mathjax text that follows. --- Johan
->> The [[http://docs.mathjax.org/en/latest/output.html|Mathjax documentation]] says, "The HTML-CSS output uses web-based fonts so that users don’t have to have math fonts installed on their computers, which introduces some printing issues in certain browsers."  And later, "The SVG output mode is high quality and slightly faster than HTML-CSS, and it does not suffer from some of the font-related issues that HTML-CSS does, so prints well in all browsers."  If you right-click on a math expression, you can change the renderer temporarily for that page to "SVG."  In my browser (FF 18), that will re-render the page such that it prints correctly.  You could change the renderer for all pages to SVG in your wiki's Mathjax configuration, or just do it within a page each time you want to print. --- Mark+>> The [[http://docs.mathjax.org/en/v2.7-latest/output.html|Mathjax documentation]] says, "The HTML-CSS output uses web-based fonts so that users don’t have to have math fonts installed on their computers, which introduces some printing issues in certain browsers."  And later, "The SVG output mode is high quality and slightly faster than HTML-CSS, and it does not suffer from some of the font-related issues that HTML-CSS does, so prints well in all browsers."  If you right-click on a math expression, you can change the renderer temporarily for that page to "SVG."  In my browser (FF 18), that will re-render the page such that it prints correctly.  You could change the renderer for all pages to SVG in your wiki's Mathjax configuration, or just do it within a page each time you want to print. --- Mark
  
 > **Spacing** in vertical direction around displayed equations ''$$e = mc^2$$'' are larger than desired if such an equation is preceeded and followed by a blank line. However, removal of blank lines reduces the source readability. What is the best practice? --- Johan > **Spacing** in vertical direction around displayed equations ''$$e = mc^2$$'' are larger than desired if such an equation is preceeded and followed by a blank line. However, removal of blank lines reduces the source readability. What is the best practice? --- Johan
plugin/mathjax.1503987653.txt.gz · Last modified: 2017-08-29 08:20 by 2a01:e35:2e29:c0c0:8ea9:82ff:fe85:2626

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki