DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:latex

LaTeX Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" no
  • 2023-04-04 "Jack Jackrum" unknown
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" no

plugin Renders inline LaTeX code

Last updated on
2011-04-29
Provides
Syntax, Admin
Repository
Source
By Alexander Krause, Michael Boyle, Mark Lundeberg

This plugin uses LaTeX+ImageMagick to render mathematical formulae embedded within a DokuWiki page. This gives a professional look to equations, and the syntax allows almost copy-paste conversion between DokuWiki and LaTeX manuscripts. For example, you may simply type $ a + b = c $ into your wiki code and it will automatically be shown as $ a + b = c $.1)

Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

:!: External requirements: This plugin requires the following software to be installed on the server hosting your wiki. If you do not have root access, contact your administrator.2)

  • A copy of LaTeX (preferably a recent version of TeXlive), which inclues both latex and dvips binaries.
  • ImageMagick, which in turn requires…
  • Ghostscript

:!: This plugin will not work in PHP safe mode. - unless your server administrator has specifically allowed access to the software this plugin needs.

:!: This plugin does not work with PHP 7 and disables DokuWiki (blank screen) with an entry in error.log: PHP Fatal error: Class syntax_plugin_latex_common contains 1 abstract method and mu st therefore be declared abstract or implement the remaining methods (dokuwiki\\Extension\\SyntaxPlugin::handle)

This can be fixed by adding the lines at the end of latexinc.php

function handle($match, $state, $pos, Doku_Handler $handler){
    return array();
}

See: https://github.com/fsiwi-hka/dokuwiki-plugin-latex/pull/1/commits/02507d33bccded74e60143355aad7ca683011739

Systems

Variously out-dated but quite in-depth installation instructions can be found on E-razor's wiki. You might also consult the similar instructions for math in MediaWiki (but note that DokuWiki's plugin does not need texvc, OCaml, etc.). Here is a summary

  • Ubuntu/Debian (works: March 2011)
    apt-get install texlive-latex-base imagemagick ghostscript
  • CentOS 53)
    yum install tetex tetex-fonts tetex-dvips tetex-latex ghostscript ImageMagick
    fmtutil-sys --all
  • Fedora Core 3
    yum install tetex-latex ImageMagick
  • Archlinux
    pacman -S texlive-most texlive-lang

    to install latex, read the latex article in the archwiki for more options

  • Windows (confirmed to work on Windows 7 with DokuWiki on a Stick –Mark April 29 2011)
    • Download and install the plugin. For some reason, plugin manager has troubles doing automatic installation on my machine. No mattery, just unpack it manually.
    • You will need to download a LaTeX installation (MikTex works), and ImageMagick. You will also need ghostscript, but this may already be provided by MikTex or some other software you have (some feedback here, anybody?). AndrewC: I needed to install GhostScript independently, as it did not come bundled with MikTex.
    • Make sure that the LaTeX and ImageMagick binaries are in the PATH variable (and restart your webserver to absorb the change), or use the plugin's configuration to set the full paths – note that you will need quotes around filenames with spaces, such as "C:\Program Files (x86)\MiKTeX 2.9\miktex\bin\latex".
      • The ImageMagick path must be at the beginning of the PATH variable, since the convert binary has the same name as a Microsoft-supplied program.
    • Should be good to go; give it a try!
  • My own experience with Windows –AndrewC, 17 March 2012
    • Just thought I would share my own experiences with this plugin, perhaps save some headaches for anyone else with a similar setup.
    • My setup is: Windows 7 64-bit, Abyss Web Server X1, DokuWiki full local installation, PHP 5.3.10 (installed using Aprelium's preconfigured PHP5 package.)
    • I installed MikTex and ImageMagick, as Mark suggested above. I also needed to install GhostScript separately, as I mentioned it's not included with ImageMagick.
    • VERY IMPORTANT: I found out (the long way ;-)) that ImageMagick and GhostScript must both be 32- or 64-bit. You can't mix and match 32- and 64-bit installations.
    • I didn't have to add any of the paths to my environment variables; it's enough to just specify the full paths to the executables in the plugin configuration.
    • No extra configuration was required. Works like a charm!
  • VERY IMPORTANT DETAIL for Windows users –Noomen, 3 Nov 2015
    • I have done all of the above and it still didn't work for me after days trying to fix this 'latex failed to render' issue. What made it finally work, and I don't know why this very important detail was not mentioned above, is using the correct path format for the different latex executables used by this plugin. Here is how windows users should enter the path to the 'latex.exe' executable for example (depending on the specific path in your case):
      "C:/Program Files (x86)/MiKTeX 2.9/miktex/bin/latex"

      that is using forward slash and primary quotation marks (these not these ').

    • and by the way to enter/change those paths you do not have to edit the 'default.php' file in the 'DokuWikiStick\dokuwiki\lib\plugins\latex\conf' folder. In the version which I have, i.e. the '2015-08-10a “Detritus”' version, you can easily do that directly in the “configuration manager”. I'm using DokuWikiStick and in this case the url to the config manager is: "http://localhost:8800/doku.php?id=start&do=admin&page=config".
  • ImageMagic setup for Windows users –Liu620, 5/27/2018
    • I have no idea about the history of ImageMagic, but identify and convert are not commands of ImageMagic-7.0.7; rather they are options for the magick command ImageMagic.
    • As a result, the setups for identify and convert should be magick identify and magick convert, respectively.
  • Windows portable version of ImageMagick (convert.exe and identify.exe) –arthur, 8th June 2018
    • After hours of struggle installing this on Windows 7, I found that downloading the portable version (ImageMagick-7.0.7-38-portable-Q16-x86.zip) of Imagemagick contains both identify.exe and convert.exe. Extracting this zip file and pointing to these files in the configuration path settings resolved this for me
      "C:/Program Files (x86)/ImageMagick-7.0.7-Q16/convert"

Examples

wiki code result
$ a + b = c $
<latex>\begin{algorithm}[H] \KwData{this text} \KwResult{how to write algorithm with \LaTeX2e } initialization\; \While{not at end of this document}{ read current\; \eIf{understand}{ go to next section\; current section becomes this one\; }{ go back to the beginning of current section\; } } \caption{How to write algorithms} \end{algorithm}</latex> it's not working properly!
\begin{eqnarray*} & & \frac{3}{4 \pi} \sqrt{4 \cdot x^2 12}\\ & & \lim_{n \to \infty} \sum_{k=1}^n \frac{1}{k^2} = \frac{\pi^2}{6}\\ & & {\it f}(x) = \frac{1}{\sqrt{x} x^2}\\ & & e^{i \pi} + 1 = 0\; \end{eqnarray*}
from ursoswald.ch

<latex>\setlength{\unitlength}{1mm} \begin{picture}(93,46) \put( 0,14){\vector(1,0){60}} \put(61,13){$x$} \put(20,4){\vector(0,1){37}} \put(19,43){$y$} \put(50,34){\circle*{2}} \put(52,35){$P$} \multiput(20,34)(4,0){8}{\line(1,0){2}} \put(14.5,33.5){$y_P$} \multiput(50,14)(0,4){5}{\line(0,1){2}} \put(48,11){$x_P$} \put( 2,8){\vector(3,1){56}} \put(59,26.5){$x'$} \multiput(50,34)(1.9,-5.7){2} {\line(1,-3){1.2}} \put(52,22){$x_P'$} \multiput(50,34)(-5.8,-1.933){6} {\line(-3,-1){3.6}} \put(12,21){$y_P'$} \put(22,8){\vector(-1,3){10.5}} \put(10,41){$y'$} \end{picture}</latex>

Syntax

The following syntax is recognized by the LaTeX plugin at the moment. For the most part, the recognized syntax is inserted as-is into a small LaTeX template (which can be changed in the Configuration Manager), then compiled:

  • $…$ syntax is rendered in-line, just as in LaTeX
  • $$…$$ syntax is rendered on its own line, just as in LaTeX
  • \begin{displaymath}…\end{displaymath} syntax
  • \begin{eqnarray}…\end{eqnarray} syntax
  • \begin{eqnarray*}…\end{eqnarray*} syntax
  • \begin{equation}…\end{equation} syntax
  • \begin{equation*}…\end{equation*} syntax
  • Special: <latex>…</latex> syntax is rendered in-line in non-math-mode. This is useful to enter environments such as picture, etc.

Caveats

  • Although the numbered-equation styles are available, the numbers do not carry over between equations. You can hard code them by including a LaTeX command like \setcounter{equation}{5}, which will reset the equation counter to start at 5.
  • The symbol $ can no longer be used for currency, so use %%$%% instead in wiki text.
  • Certain words are blacklisted from being included in LaTeX code – for example $ L_{\rm name} $ will show as Fail: triggered security filter; contains blacklisted LaTeX tags. because “name” is blacklisted (I am not sure why, but I'm keeping the old blacklist just in case –Mark). The image title tag (tooltip) will indicate that this is the case, emulated here: Fail: triggered security filter; contains blacklisted LaTeX tags..

Configuration/Settings

From the Configuration Manager, you can modify the following settings:

  • Media namespace in which to store images (default is :wiki:latex).
  • Image type: default is png.
  • Maximum allowed image size.
  • Maximum allowed length of LaTeX code (sort of a security filter).
  • Paths to latex, dvips, convert, and identify programs.
  • Options to convert program, to control image size, transparency.
  • The LaTeX template used for each rendered block: add \usepackage{} statements here, change color, etc.
    • Please give an example as how and where to add \usepackage{}. For example, add the algorithm2e package used in a previous example. Thanks a lot–Liu620, 5/27/2018.
      • Ok, got this figured out. For details see the next paragraph. Liu620, 5/28/2018.

To use your favorite LaTex packages, you need to add them using \\usepackage{…} to the default.php file located in the …\dokuwiki\lib\plugins\latex\conf folder. You can put the “use package” statements any where in the block of existing “use package” statements. After adding \\usepackage{tikz} and \\usepackage{algorithm2e}, drawings and algorithms produced using TikZ and algorithm2e, respectively, all work nicely. Some other packages should work as well.

Admin plugin

There is an admin plugin included for ease in managing the LaTeX image cache, which can easily grow to thousands of equations in size. This can be accessed through the administration actions panel.

The admin plugin also allows you to troubleshoot problems in the rendering process.

Troubleshooting

  • If the plugin settings are incorrect (or you are missing some external software), you will see instead of the image. The image will have a tooltip (html title tag) indicating the particular error.
  • Try a test run of your LaTeX installation from the admin panel of the LaTeX plugin. Besides a tooltip, you will see information on:
    • Existence and versions of latex, dvips, convert, and identify binaries.
    • The LaTeX file to be compiled.
    • The ouput (stdout/stderr) of all the commands used.
    • The .log file from LaTeX compilation.
  • This LaTeX plugin is similar in operation to the LaTeX plugins of other wiki software. Check the MediaWiki LaTeX troubleshooting guide for possible solutions, though note for example that the DokuWiki plugin does not use texvc.
  • In php.ini “exec” should not appear in the disable_functions list

Specific issues

  • Some ancient LaTeX installations may work only if you remove the inputenc package from the preamble, but this is not the preferred method since DokuWiki uses UTF-8.
  • Missing latex.fmt. This is a bug found in CentOS 5, due to the packages failing to update the proper files. Quite confusingly, normal users are able to use LaTeX with no problems but all web-invoked LaTeX will fail (the apache user cannot write to its home directory /var/www/.). You can either:
    • Run the following command as root4)
      fmtutil-sys --all

      or, if that does not work,

    • Run LaTeX as a normal user allowing LaTeX to generate its own latex.fmt in your home directory, then copy that latex.fmt into your temporary directory where the DokuWiki LaTeX plugin can find it.5) You can find the file at $HOME/.texmf-var/web2c/latex.fmt. You may want to relocate the temporary folder to be inside your DokuWiki installation, so that latex.fmt is not wiped out by a temporary files cleaner.
  • Invalid drive specification. This error appears in the troubleshooter's program versions test in Windows. The plugin attempts to call convert but it gets Microsoft's program rather than the ImageMagick one. Adjust your PATH environment variable or configure the plugin to use an absolute path.

Development

This plugin was originally written by Alexander 'E-razor' Krause based on class.latexrender.php by Benjamin Zeiss then extended by Michael Boyle, and is now maintained on github by Mark Lundeberg.

  • March 4 2011 - Mark Lundeberg
    • starting with Michael Boyle version (which enabled $…$, <latex></latex>, \begin{displaymath}, \begin{eqnarray}, \begin{eqnarray*})
    • changed inlines to have vertical-alignment:middle; (not perfect, but close)
    • changed big equations to have nicer CSS margins.
    • added DokuTexit render mode, following suggestion on E-Razor's page
    • restructured files to share a common class
    • added several config options to config manager (paths of binaries, colour, formula size, image format)
    • added support for $$ … $$ as in LaTeX, for displayed equations.
    • added support for \begin{equation} and \begin{equation*}.
    • uploaded the plugin here where other people can find it.
  • March 6 2011
    • added admin page for cache wiping/cleaning.
    • binary paths now include options, as applicable.
    • added config options for preamble/postamble.
    • added config options for max formula sizes
    • added a minimal ODT render mode.
    • added informative tooltip text on images of failed renders.
  • March 9 2011
    • added troubleshooter to admin panel
  • April 24 2011
    • Changed image namespace to :wiki:latex (avoids polluting root namespace)
    • Changed temporaries to a media namespace: :wiki:latex:tmp (allows access to temporary files, through the wiki itself!)
  • April 28/29 2011
    • Removed keep_tmp option and removed program options from configuration (only paths specified now).
    • Made compatible with Windows – works with DokuWiki on a Stick, MikTex, and ImageMagick official binaries, essentially out-of-the-box.

Discussion

Local with MacTeX: LaTeX compilation failed

On OS X 10.8, I have a local and up to date DokuWiki installation, which works fine. Further, I have installed the latex plugin and a standard MacTeX (up to date) installation. LaTeX works fine when I compile the tex code provided the plugin.

Using the latex plugin in DokuWiki instead produces “LaTeX render failed” with the hint “LaTeX compilation failed”.

Could you please give me a hand for making the plugin work? Christian

Me too!! I have the same problem

As a quick and dirty fix, try putting the absolute paths (the ones that show up when you type, e.g., which latex) into the file dokuwiki/lib/plugins/latex/conf/default.php, e.g.,

  • Old file
    $conf['latex_path'] = 'latex';
    $conf['dvips_path'] = 'dvips';
    $conf['convert_path'] = 'convert';
    $conf['convert_options'] = '-density 120 -trim -transparent "#FFFFFF"';
    $conf['identify_path'] = 'identify';
    $conf['image_format'] = 'png';
    $conf['latex_namespace'] = 'wiki:latex';
  • New file
    $conf['latex_path'] = '/usr/texbin/latex';
    $conf['dvips_path'] = '/opt/local/bin/dvips';
    $conf['convert_path'] = '/opt/local/bin/convert';
    $conf['convert_options'] = '-density 120 -trim -transparent "#FFFFFF"';
    $conf['identify_path'] = '/opt/local/bin/identify';
    $conf['image_format'] = 'png';
    $conf['latex_namespace'] = 'wiki:latex';

Misc

  • Great! It works! Thanks for supporting me in installation. — thuanle 2011/03/11 16:26

Control over the Images

If the embedded images are not perfectly aligned, you can gain more control by adding 'media_latex' to the class in syntax.php lines 91 and 96. After that create an style.css with 'img.media_latex{ … }'.

I'm not sure if that applies for the current plugin (there's no syntax.php), and anyway there are already two CSS styles declared in plugins/latex/all.css : The first style img.latex_displayed is for equations on their own line such as $$ G(x) = 2 $$, which have a slight indent. The second style img.latex_inline sets vertical alignment to middle for in-line latex such as $a + b = c$. -Mark

Color settings

After installation, the default color is dark red.

How to set the default color to black:

Go to: Administration > Configuration Settings > Plugin Settings > Latex Plugin Settings > plugin-latex-preamble.

Delete the following two lines:

\definecolor{MyColour}{rgb}{0.50,0.00,0.00}
{\color{MyColour}

Click “Save”, and you're done.

Dollar Signs

Maybe a stupid question but how can I display the Dollars symbol ($) on the page ? The plugin replace all my $ by the message “Latex render failed” It's not very easy to use %%$%% !
Yes, that's an unfortunate side effect of the plugin. If you don't mind losing the $ a+b $ syntax entirely, you can delete plugins/latex/syntax/dollar.php. Another way you could consider is to add a space to dollar.php line 14, changing the trigger pattern from
$this->Lexer->addEntryPattern('\$(?=.*\$)',$mode,'plugin_latex_dollar');

to

$this->Lexer->addEntryPattern('\$ (?=.*\$)',$mode,'plugin_latex_dollar');

That way, the plugin would only activate on text like ”the sum $ a+b $“ where the $ is followed by a space, and would not activate on text like ”projected total cost of $2000“. -Mark

Well, why don't you try <nowiki>? -Di

=== mask $*Dollar*$ as in /* comment */ plugin

Instead of a space add an * to the EntryPattern and the ExitPattern in dollar.php.
1. This is a very rare combination and
2. it will work for all those languages which have a currency symbol after the ammount. E.g. in many european countries we are used to write 2.000,00$
3. It will not break all existing pages.
So change dolar.php to:
$this->Lexer->addEntryPattern('\$\*(?=.*\$)',$mode,'plugin_latex_dollar');  

and also add an * to the ExitPattern:

function postConnect() { $this->Lexer->addExitPattern('\*\$','plugin_latex_dollar'); }

The syntax will change to $* a + b = c *$ which is close to the comment-plugin Syntax (/* a comment */. And $2000, 2.000,00$ and a $ alone will work as before.
-TT, 2013-02-28

ReadOnly-Access

If i give the group @ALL an “Read”-Permission to read the page, they can access and read the normal Text…but the Latex-Image are not there! What to do?
Solved! Need to give “Read”-Permission to “wiki:latex:*”

Toolbar buttons disappear

The DokuWiki toolbar buttons were not visible anymore after installation of the Latex plug-in (Using a fresh install with QuickPHP / Firefox12 / DokuWiki Angua / default template / default settings). As a solution, I disabled and then enabled the Latex plug-in (This does not “prove” that this plug-in is the actual cause). Can anybody confirm this?

Latex syntax in tables

Generally, latex does not work in a table. For example,

|  \begin{equation*} e=mc^2 \end{equation*}  |

results in:

\begin{equation*} e = mc2 \end{equation*}
Strange, it works here!
-TT, 2013-02.28

Not rendering Latex Code

Plugin does not render any latex code in dokuwiki pages, displays only the text as if not recognizing the syntax. No images in corresponding image folder. With admin tool everything is working fine. Found no error messages or anything. Any hints?

See Latex Render Failure #9 on the GitHub page of the plugin : permission problem with ImageMagick policies. “They can be set in /etc/ImageMagick-6/policy.xml. In particular you should change the line <policy domain=“coder” rights=“none” pattern=“PS” /> to <policy domain=“coder” rights=“read” pattern=“PS” />”

Converting to PDF

There are a few plugins to convert the pages to pdf, for example:

https://www.dokuwiki.org/plugin:dw2pdf

Unfortunately I am not able to see the latex formulas in the pdf document. Anyone have any idea how to fix this or know of a dokuwiki to pdf convert that acutally works with this latex plugin?

dw2pdf does not seem to work with (some) transparent png images. Either try setting the imagetype in the laxtex config to jpg or if you want the png add -alpha remove to the convert options
-PT, 2015-02-22
An idea how to fix this (at least in Firefox, Linux of course):
add ?do=export_html to the address line of your Firefox and press Enter. Then use ctrl+p to start the print dialog. Choose print to file + pdf and voilla, there it is a pdf export with all latex parts.
-TT, 2013-02-28

Blacklist

It is mentioned above that some words are blacklisted and that the blacklist is kept “just in case”. The presence of blacklisted words causes the error “Fail: triggered security filter; contains blacklisted LaTeX tags”. Where can one find the blacklist? — krichter 2014-08-13 14:43

From class.latexrender.php

var $_latex_tags_blacklist = array(
	   "include","def","command","loop","repeat","open","toks","output","input",
	   "catcode","name","^^",
	   "\\every","\\errhelp","\\errorstopmode","\\scrollmode","\\nonstopmode","\\batchmode",
	   "\\read","\\write","csname","\\newhelp","\\uppercase", "\\lowercase","\\relax","\\aftergroup",
	   "\\afterassignment","\\expandafter","\\noexpand","\\special"
	    );

This would be my guess. — Chris_P

Blacklist

Maintained (patched) version of this plugin can be found at latex-was.

plugin/latex.txt · Last modified: 2024-03-16 03:12 by KaiMartin

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