New in 2.5.0: Allow reference numbers to be set in brackets (Issue #57).

New in 2.4.0: Updated to work with pandoc 2.11.

more...

pandoc-eqnos 2.5.0

pandoc-eqnos is a pandoc filter for numbering equations and their references when converting markdown to other formats. It is part of the pandoc-xnos filter suite. LaTeX/pdf, html, and epub output have native support. Native support for docx output is a work in progress.

Demonstration: Processing demo3.md with pandoc + pandoc-eqnos gives numbered equations and references in pdf, tex, html, epub, docx and other formats (including beamer slideshows).

This version of pandoc-eqnos was tested using pandoc 1.15.2 - 2.11.1.1,¹ and may be used with linux, macOS, and Windows. Bug reports and feature requests may be posted on the project's Issues tracker. If you find pandoc-eqnos useful, then please kindly give it a star on GitHub.

See also: pandoc-fignos, pandoc-tablenos, pandoc-secnos
Other filters: pandoc-comments, pandoc-latex-extensions

Contents

1. Installation
2. Usage
3. Markdown Syntax
4. Customization
5. Technical Details
6. Getting Help
7. Development
8. What's New

Installation

Pandoc-eqnos requires python. It is easily installed -- see here.² Either python 2.7 or 3.x will do.

Pandoc-eqnos may be installed using the shell command

pip install pandoc-eqnos --user

and upgraded by appending --upgrade to the above command. Pip is a program that downloads and installs software from the Python Package Index, PyPI. It normally comes installed with a python distribution.³

Instructions for installing from source are given in DEVELOPERS.md.

Usage

Pandoc-eqnos is activated by using the

--filter pandoc-eqnos

option with pandoc. Alternatively, use

--filter pandoc-xnos

to activate all of the filters in the pandoc-xnos suite (if installed).

Any use of --filter pandoc-citeproc or --bibliography=FILE should come after the pandoc-eqnos or pandoc-xnos filter calls.

Markdown Syntax

The cross-referencing syntax used by pandoc-eqnos was developed in pandoc Issue #813 -- see this post by @scaramouche1.

To mark an equation for numbering, add an identifier to its attributes:

$$ y = mx + b $$ {#eq:id}

The prefix #eq: is required. id should be replaced with a unique string composed of letters, numbers, dashes and underscores. If id is omitted then the equation will be numbered but unreferenceable.

To reference the equation, use

@eq:id

or

{@eq:id}

Curly braces protect a reference and are stripped from the output.

Demonstration: Processing demo.md with pandoc + pandoc-eqnos gives numbered equations and references in pdf, tex, html, epub, docx and other formats.

Clever References

Writing markdown like

See eq. @eq:id.

seems a bit redundant. Pandoc-eqnos supports "clever references" 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 references are enabled by default (see Customization, below), then users may disable it for a given reference using⁴

!@eq:id

Demonstration: Processing demo2.md with pandoc + pandoc-eqnos gives numbered equations and references in pdf, tex, html, epub, docx and other formats.

Note: When using *@eq:id and emphasis (e.g., *italics*) in the same sentence, the * in the clever reference must be backslash-escaped; i.e., \*@eq:id.

Tagged Equations

The equation number may be overridden by placing a tag in the equation's attributes block:

$$ 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.