pandoc-eqnos is a pandoc filter for numbering equations and equation references in markdown documents.
Demonstration: Processing demo.md with pandoc --filter pandoc-eqnos gives numbered equations and references in pdf, tex, html, epub, md and other formats.
This version of pandoc-eqnos was tested using pandoc 1.17.2, 1.16.0.2 and 1.15.2. It works under linux, Mac OS X and Windows. Older versions and other platforms can be supported on request.
Installation of the filter is straight-forward. It is simple to use and has been tested extensively. I am pleased to receive bug reports and feature requests on the project's Issues tracker.
See also: pandoc-fignos, pandoc-tablenos
Equation numbers and references are frequently used in academic writing, but are not supported by pandoc. Pandoc-eqnos is an add-on filter that provides the missing functionality.
The markdown syntax recognized by pandoc-eqnos was developed in pandoc Issue #813 -- see this post by @scaramouche1. It seems likely that this will be close to what pandoc ultimately adopts. Pandoc-eqnos is a transitional package for those who need equation numbers and references now.
To apply the filter, use the following option with pandoc:
--filter pandoc-eqnos
Note that any use of --filter pandoc-citeproc or --bibliography=FILE options should come after the pandoc-eqnos filter call.
The basic syntax is taken from this post in pandoc Issue #813. The extended syntax goes further.
To number an equation, add the label eq:id to its attributes:
$$ y = mx + b $$ {#eq:id}
The prefix #eq: is required. id should be replaced with a unique identifier composed of letters, numbers, dashes, slashes and underscores. If id is omitted then the figure will be numbered but unreferenceable.
To reference the equation, use
@eq:id
or
{@eq:id}
Curly braces around a reference are stripped from the output.
See demo.md for an example.
Writing markdown like
See eq. @eq:id.
seems a bit redundant. Pandoc-eqnos supports "clever referencing" via single-character modifiers in front of a reference. You can write
See +@eq:id.
to have the reference name (i.e., "eq.") automatically generated. The above form is used mid-sentence. At the beginning of a sentence, use
*@eq:id
instead. If clever referencing is enabled by default (see Customization, below), you can disable it for a given reference using
!@eq:id
Demonstration: Processing demo2.md with pandoc --filter pandoc-eqnos gives numbered equations and references in pdf, tex, html, epub, md and other formats.
Note: If you use *eq:id and emphasis (e.g., *italics*) in the same sentence, then you must backslash escape the * in the clever reference; e.g., \*eq:id.
Note: The disabling modifier "!" is used instead of "-" because pandoc unnecessarily drops minus signs in front of references.
You may optionally override the equation number by placing a tag in an equation's attributes block as follows:
$$ y = mx + b $$ {#eq:id tag="B.1"}
The tag may be arbitrary text, or an inline equation such as $\mathrm{B.1'}$. Mixtures of the two are not currently supported.
Pandoc-eqnos may be customized by setting variables in the metadata block or on the command line (using -M KEY=VAL). The following variables are supported:
-
eqnos-cleverefor justcleveref- Set toOnto assume "+" clever references by default; -
eqnos-plus-name- Sets the name of a "+" reference (e.g., change it from "eq." to "equation"); and -
eqnos-star-name- Sets the name of a "*" reference (e.g., change it from "Equation" to "Eq.").
Demonstration: Processing demo3.md with pandoc --filter pandoc-eqnos gives numbered equations and references in pdf, tex, html, epub, md and other formats.
For TeX/pdf output:
- The
equationenvironment is used; - Tagged equations make use of the
\tagmacro; - The
\labeland\refmacros are used for equation labels and references; and - The clever referencing macros
\crefand\Crefare used if they are available (i.e. included in your LaTeX template via\usepackage{cleveref}), otherwise they are faked. Set the meta variablexnos-cleveref-faketoOffto disable cleveref faking.
For all other formats the numbers/tags and clever references are hanr-coded into the output.
Links are constructed for html and pdf output.
Pandoc-eqnos requires python, a programming language that comes pre-installed on linux and Mac OS X, and which is easily installed on Windows. Either python 2.7 or 3.x will do.
Install pandoc-eqnos as root using the shell command
pip install pandoc-eqnos
To upgrade to the most recent release, use
pip install --upgrade pandoc-eqnos
Pip is a program that downloads and installs modules from the Python Package Index, PyPI. It should come installed with your python distribution.
If you are prompted to upgrade pip, then do so. Installation errors may occur with older versions. The command is
python -m pip install --upgrade pip
If you are running linux, pip may be packaged separately from python. On Debian-based systems (including Ubuntu), you can install pip as root using
apt-get update
apt-get install python-pip
During the install you may be asked to run
easy_install -U setuptools
owing to the ancient version of setuptools that Debian provides. The command should be executed as root. You may now follow the standard installation procedure given above.
It is easy to install python on Windows. First, download the latest release. Run the installer and complete the following steps:
-
Install Python pane: Check "Add Python 3.5 to path" then click "Customize installation".
-
Optional Features pane: Click "Next".
-
Advanced Options pane: Optionally check "Install for all users" and customize the install location, then click "Install".
Once python is installed, start the "Command Prompt" program. Depending on where you installed python, you may need elevate your privileges by right-clicking the "Command Prompt" program and selecting "Run as administrator". You may now follow the standard installation procedure given above. Be sure to close the Command Prompt program when you have finished.
If you have any difficulties with pandoc-eqnos, or would like to see a new feature, please file an Issue on GitHub.