Awesome

New in 2.2.2: Updated for pandoc 2.10.1. Fixed section number offset problem for html output (Issue #2).

more...

pandoc-secnos 2.2.2

pandoc-secnos is a pandoc filter for numbering section 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-secos gives numbered section references in pdf, tex, html, epub, docx and other formats.

This version of pandoc-secnos was tested using pandoc 1.15.2 - 2.10.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-secnos useful, then please kindly give it a star on GitHub.

See also: pandoc-fignos, pandoc-eqnos, pandoc-tablenos
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-secnos requires python. It is easily installed -- see here.² Either python 2.7 or 3.x will do.

Pandoc-secnos may be installed using the shell command

pip install pandoc-secnos --user

and upgrade 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-secnos is activated by using the

--filter pandoc-secnos

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-secnos or pandoc-xnos filter calls.

Markdown Syntax

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

For LaTeX/pdf, html, and epub output, sections are numbered using pandoc's --number-sections option.

To reference a section, use

@sec:id

or

{@sec:id}

The prefix @sec: is required. id should be replaced with a unique identifier for the section, composed of letters, numbers, dashes and underscores. Curly braces protect a reference and are stripped from the output.

Pandoc automatically assigns an identifier to each section title in a document. For example, the identifier for

Section One
===========

is section-one; a reference to it would be @sec:section-one. An identifier may be explicitly assigned to the section title using attributes as follows:

Section Two {#sec:2}
===========

A reference to this would be @sec:2.

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

Clever References

Writing markdown like

See sec. @sec:id.

seems a bit redundant. Pandoc-secnos supports "clever references" via single-character modifiers in front of a reference. Users may write

 See +@sec:id.

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

 *@sec:id

instead. If clever references are enabled by default (see Customization, below), then users may disable it for a given reference using⁴

!@sec:id

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

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

Disabling Links

To disable a link on a reference, set nolink=True in the reference's attributes:

@sec:id{nolink=True}

Customization

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

• secnos-warning-level or xnos-warning-level - Set to 0 for no warnings, 1 for critical warnings, or 2 (default) for all warnings. Warning level 2 should be used when troubleshooting.

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

• xnos-capitalise - Capitalises the names of "+" clever references (e.g., change from "section" to "Section");

• secnos-plus-name - Sets the name of a "+" clever reference (e.g., change it from "section" to "sec."). Settings here take precedence over xnos-capitalise;

• secnos-star-name - Sets the name of a "*" clever reference (e.g., change it from "Section" to "Sec.");

• xnos-number-offset - Set to an integer to offset the section numbers in references. For html and epub output, this feature should be used together with pandoc's --number-offset option set to the same integer value. For LaTeX/PDF, this option offsets the actual section numbers as required.

Note that variables beginning with secnos- apply to only pandoc-secnos, whereas variables beginning with xnos- apply to all all of the pandoc-fignos/eqnos/tablenos/secnos filters.

Demonstration: Processing demo3.md with pandoc + pandoc-secnos gives numbered section references in pdf, tex, html, epub, docx and other formats.

Technical Details

LaTeX/pdf Output

During processing, pandoc-secnos inserts packages and supporting LaTeX into the header-includes metadata field. To see what is inserted, set the secnos-warning-level meta variable to 2. Note that any use of pandoc's --include-in-header option overrides all header-includes.

An example reference in LaTeX looks like

See \cref{sec:1}.

Other details:

• The cleveref and caption packages are used for clever references and caption control, respectively;
• The \label and \ref macros are used for section labels and references, respectively (\Cref and \cref are used for clever references);
• Clever reference names are set with \Crefname and \crefname;

Html/Epub Output

An example reference in html looks like

See section <a href="#sec:1">1</a>.

Docx Output

Docx OOXML output is under development and subject to change. Native capabilities will be used wherever possible.

Getting Help

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

Development

Pandoc-secnos will continue to support pandoc 1.15-onward and python 2 & 3 for the foreseeable future. The reasons for this are that a) some users cannot upgrade pandoc and/or python; and b) supporting all versions tends to make pandoc-secnos more robust.

Developer notes are maintained in DEVELOPERS.md.

What's New

New in 2.2.2: Updated for pandoc 2.10.1. Fixed section number offset problem for html output (Issue #2).

New in 2.1.1: Warnings are now given for duplicate reference targets.

New in 2.0.0: Pandoc-secnos is a new filter. It has been marked with version number 2.0.0 in keeping with the major version number of the underlying pandoc-xnos library.

Footnotes

<a name="footnote1">1</a>: Pandoc 2.4 broke how references are parsed, and so is not supported.

<a name="footnote2">2</a>: For MacOS, my preferred install method is to use the package available from python.org.

<a name="footnote3">3</a>: Anaconda users may be tempted to use conda instead. This is not advised. The packages distributed on the Anaconda cloud are unofficial, are not posted by me, and in some cases are ancient. Some tips on using pip in a conda environment may be found here.

<a name="footnote4">4</a>: The disabling modifier "!" is used instead of "-" because pandoc drops minus signs in front of references.