Skip to content
A pandoc filter for numbering figures and figure references.
Python Makefile TeX
Branch: master
Clone or download

Notice: A beta release for pandoc-fignos 2.0.0 is now available. It can be installed using

pip install pandoc-fignos --upgrade --pre --user

Please read the beta's documentation and in particular about What's New first.

pandoc-fignos 1.4.2

pandoc-fignos is a pandoc filter for numbering figures and figure references when converting markdown documents to other formats.

Demonstration: Processing with pandoc --filter pandoc-fignos gives numbered figures and references in pdf, tex, html, epub, docx and other formats (including beamer slideshows).

This version of pandoc-fignos was tested using pandoc 1.15.2 - 2.7.21. It works under linux, Mac OS X and Windows. I am pleased to receive bug reports and feature requests on the project's Issues tracker. If you find pandoc-fignos useful, then please kindly give it a star on GitHub.

See also: pandoc-eqnos, pandoc-tablenos


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


Use the following option with pandoc:

--filter pandoc-fignos

Note that any use of --filter pandoc-citeproc or --bibliography=FILE should come after the pandoc-fignos filter call.

Markdown Syntax

The markdown syntax extension used by pandoc-fignos was developed in pandoc Issue #813 -- see this post by @scaramouche1.

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


Alternatively, use reference link attributes. The prefix #fig: is required. id should be replaced with a unique string composed of letters, numbers, dashes and underscores. If id is omitted then the figure will be numbered but unreferenceable.

To reference the figure, use




Curly braces around a reference are stripped from the output.

Demonstration: Processing with pandoc --filter pandoc-fignos gives numbered figures and references in pdf, tex, html, epub, docx and other formats.

Clever References

Writing markdown like

See fig. @fig:id.

seems a bit redundant. Pandoc-fignos supports "clever referencing" via single-character modifiers in front of a reference. You can write

 See +@fig:id.

to have the reference name (i.e., "fig.") automatically generated. The above form is used mid-sentence. At the beginning of a sentence, use


instead. If clever referencing is enabled by default (see Customization, below), then you can disable it for a given reference using2


Demonstration: Processing with pandoc --filter pandoc-fignos gives numbered figures and references in pdf, tex, html, epub, docx and other formats.

Note: If you use *fig:id and emphasis (e.g., *italics*) in the same sentence, then you must backslash escape the * in the clever reference; e.g., \*fig:id.

Tagged Figures

You may optionally override the figure number by placing a tag in a figure's attributes block as follows:

![Caption.](image.png){#fig:id tag="B.1"}

The tag may be arbitrary text, or an inline equation such as $\text{B.1}'$. Mixtures of the two are not currently supported.


Pandoc-fignos may be customized by setting variables in the metadata block or on the command line (using -M KEY=VAL). The following variables are supported:

  • fignos-capitalise or xnos-capitalise - Capitalizes the names of "+" references (e.g., change from "fig." to "Fig.");

  • fignos-caption-name - Sets the name at the beginning of a caption (e.g., change it from "Figure to "Fig." or "图");

  • fignos-cleveref or xnos-cleveref - Set to True to assume "+" clever references by default;

  • fignos-plus-name - Sets the name of a "+" reference (e.g., change it from "fig." to "figure"); and

  • fignos-star-name - Sets the name of a "*" reference (e.g., change it from "Figure" to "Fig.").

  • xnos-number-sections - Set to True so that figures are numbered per section (i.e. Fig. 1.1, 1.2, etc in Section 1, and Fig 2.1, 2.2, etc in Section 2). See Figure Numbering by Section, below.

    This feature is only presently enabled for html, LaTeX/pdf, and docx.

  • xnos-cleveref-fake - Sets cleveref faking on/off (LaTeX/pdf only). See Technical Details, below.

Demonstration: Processing with pandoc --filter pandoc-fignos gives numbered figures and references in pdf, tex, html, epub, docx and other formats.

Figure Numbering by Section

Pandoc's --number-sections option enables section numbering for LaTeX/pdf and html output. For docx, use custom styles instead. Figure numbering by section (e.g., "Fig. 2.1") can then be obtained as follows:

  1. html and docx: Add xnos-number-sections: True to your YAML metadata or use the -M xnos-number-sections=True option with pandoc. This variable is ignored for other output formats.

  2. LaTeX/pdf: Add header-includes: \numberwithin{figure}{section} to your YAML metadata. If you need multiple header includes, then add something like this:

      - \numberwithin{figure}{section}
      - \numberwithin{equation}{section}
      - \numberwithin{table}{section}

    Alternatively, write your header includes into FILE, and use the --include-in-header=FILE option with pandoc.

    If you set either --top-level-division=part or --top-level-division=chapter then these header includes can be dropped.

    LaTeX header-includes are ignored for html output.

Latex/PDF Specializations

To make internal links target the top of a figure (rather than its caption), add \usepackage{caption} to the header-includes field of your document's YAML metadata. To make the figure caption label bold, add \usepackage[labelfont=bf]{caption} instead. See the LaTeX caption package documentation for additional features.

Technical Details


  • The \label and \ref macros are used for figure labels and references (links are automatically generated);
  • \figurename is set for the caption name;
  • Tags are supported by temporarily redefining \thefigure around a figure; and
  • The clever referencing macros \cref and \Cref are used if they are available (i.e. included in your LaTeX template via \usepackage{cleveref}), otherwise they are faked. Set the meta variable xnos-cleveref-fake to False to disable cleveref faking.
  • The clever reference names are set using \crefformat and \Crefformat. For this reason the cleveref package's capitalise parameter has no effect. Use the fignos-capitalise meta variable instead.


  • Links to figures use html's and docx's native capabilities; and

  • The numbers, caption name, and (clever) references are hard-coded into the output.


Pandoc-fignos 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.

Standard installation

Install pandoc-fignos (as root) using the shell command

pip install pandoc-fignos

To upgrade to the most recent release, use

pip install --upgrade pandoc-fignos

Pip is a program that downloads and installs modules from the Python Package Index, PyPI. It should come installed with your python distribution.

Note that on some systems for python3 you may need to use pip3 instead.


If you are prompted to upgrade pip, then do so. Installation errors may occur with older versions. The command you need to execute (as root) is

python -m pip install --upgrade pip

One user reported that they had to manually upgrade the six and setuptools modules:

pip install --upgrade six
pip install pandoc-fignos

This should not normally be necessary.

You may test the installation as a regular user using the shell command

which pandoc-fignos

This will tell you where pandoc-fignos is installed. If it is not found, then please submit a report to our Issues tracker.

To determine which version of pandoc-fignos you have installed, use

pip show pandoc-fignos

As of pandoc-fignos 1.4.2 you can also use

pandoc-eqnos --version

Please be sure you have the latest version installed before reporting a bug on our Issues tracker.

Installing on linux

If you are running linux, then 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.

Installing on Mac OS X

To install as root on Mac OS X, you will need to use the sudo command. For example:

sudo pip install pandoc-fignos

Troubleshooting should be done as a regular user (i.e., without using sudo).

Installing on Windows

It is easy to install python on Windows. First, download the latest release. Run the installer and complete the following steps:

  1. Install Python pane: Check "Add Python 3.5 to path" then click "Customize installation".

  2. Optional Features pane: Click "Next".

  3. 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 to 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.

Getting Help

If you have any difficulties with pandoc-fignos, or would like to see a new feature, then please submit a report to our Issues tracker.

What's New

New in 1.4.1: Fixed support for docx equation numbering by section.

New in 1.4.0: Support for references in bracketed spans.

New in 1.3.2: Support for docx equation numbering by section.

New in 1.3.0: Boolean metadata values must now be one of true, True TRUE, false, False, or FALSE. This is following a change of behaviour with pandoc 2.2.2.

New in 1.2.0: Added fignos-capitalise meta variable to capitalise clever references (e.g., change "fig." to "Fig.").


1: Pandoc 2.4 broke how references are parsed, and so is not supported.

2: The disabling modifier "!" is used instead of "-" because pandoc unnecessarily drops minus signs in front of references.

You can’t perform that action at this time.