Welcome to pandoc-numbering’s documentation!

Install

pandoc-numbering is a pandoc filter for numbering all kinds of things.

Instructions

pandoc-numbering requires python, a programming language that comes pre-installed on linux and Mac OS X, and which is easily installed on Windows.

Install pandoc-numbering using the bash command

$ pipx install pandoc-numbering

To upgrade to the most recent release, use

$ pipx upgrade pandoc-numbering

pipx is a script to install and run python applications in isolated environments from the Python Package Index, PyPI. It can be installed using instructions given here.

Make sure you have the

tocloft

LaTeX package. On linux you have to install some extra libraries before pandoc-numbering. On a Debian-based system (including Ubuntu), you can install it as root using

$ sudo apt-get install texlive-latex-extra

Getting Help

If you have any difficulties with pandoc-numbering, please feel welcome to file an issue on github so that we can help.

Contribute

Instructions

Install poetry, then run

$ poetry install
$ poetry shell

And submit your changes. When you commit, hooks will be executed to check your code.

Notes

format icon by Picol
license icon by Icooon Mono
download icon by zest
status icon by Just Icon
code style icon by Google Material Design icons
size icon by Iconscout

Usage

Run pandoc using pandoc-numbering filter:

$ pandoc --filter pandoc-numbering

Numbering

Each paragraph or the first line of a description list ended by a numbering-marker will be numbered. The description preceding the numbering-marker can be used as a category name by converting it to an auto-identifier. There can be an optional title enclosed in parentheses between the description and the numbering-marker.

Thus the syntax for automatic-numbering is:

where:

description-category is a significant text (i.e. Exercise)
title is a optional title text enclosed in parentheses (i.e. (This is the first exercise))
numbering-marker is a special string mainly containing a # character (preceded by an optional sectioning part and followed by an optional prefix part and an optional name part). If there is a prefix part, the category is set to that prefix part.

When a new (category, sectioning) couple is parsed, a new counter is set to 1. This counter is used to number this paragraph and all the paragraphs which use the same couple.

Thus:

Exercise #

Exercise #
:   Text for the exercise

will be rendered as

**Exercise 1**

**Exercise 2**
:   Text for the exercise

The optional title will be rendered at the end of the paragraph. Thus:

Exercise (This is the first exercise) #

Exercise (This is the second exercise) #

will be rendered as

**Exercise 1** *(This is the first exercise)*

**Exercise 2** *(This is the second exercise)*

The syntax for a numbering-marker is:

The optional sectioning part is composed of a hidden-sectioning part and of a visible-sectioning part.

The hidden-sectioning part is composed of an optional sequence of -. characters

The visible-sectioning part is composed of an optional sequence of +. characters.

The sectioning part is used to

reset the count number for a given category when the headers change.
number the paragraphs.

Thus, if you use the visible-sectioning part:

First section
=============

Exercise +.#

Exercise +.#

Second section
==============

Exercise +.#

Exercise +.#

will be rendered as

First section
=============

**Exercise 1.1**

**Exercise 1.2**

Second section
==============

**Exercise 2.1**

**Exercise 2.2**

If you use the hidden-sectioning part, the header numbers are not shown. Thus:

First section
=============

Exercise -.#

Exercise -.#

Second section
==============

Exercise -.#

Exercise -.#

will be rendered as

First section
=============

**Exercise 1**

**Exercise 2**

Second section
==============

**Exercise 1**

**Exercise 2**

Note that the second section has reset the exercises’ numbering that use the -. sectioning part.

If you use the hidden-sectioning part and the visible-sectioning part:

First section
=============

First sub-section
-----------------

Exercise -.+.#

Exercise -.+.#

Second sub-section
-----------------

Exercise -.+.#

Exercise -.+.#

Second section
==============

First sub-section
-----------------

Exercise -.+.#

Exercise -.+.#

Second sub-section
-----------------

Exercise -.+.#

Exercise -.+.#

will be rendered as:

First section
=============

First sub-section
-----------------

**Exercise 1.1**

**Exercise 1.2**

Second sub-section
------------------

**Exercise 2.1**

**Exercise 2.2**

Second section
==============

First sub-section
-----------------

**Exercise 1.1**

**Exercise 1.2**

Second sub-section
------------------

**Exercise 2.1**

**Exercise 2.2**

For the examples given above, the real rendering is more complex. The paragraphs are enclosed in a span element whose identifier is constructed using the category, the sectioning, the prefix and the name. This can be used to cross-refer these numbered paragraphs.

The last example is really rendered as:

First section
=============

First sub-section
-----------------

[**Exercise 1.1**]{#exercise:1.1.1 .pandoc-numbering-text .exercise}

[**Exercise 1.2**]{#exercise:1.1.2 .pandoc-numbering-text .exercise}

Second sub-section
------------------

[**Exercise 2.1**]{#exercise:1.2.1 .pandoc-numbering-text .exercise}

[**Exercise 2.2**]{#exercise:1.2.2 .pandoc-numbering-text .exercise}

Second section
==============

First sub-section
-----------------

[**Exercise 1.1**]{#exercise:2.1.1 .pandoc-numbering-text .exercise}

[**Exercise 1.2**]{#exercise:2.1.2 .pandoc-numbering-text .exercise}

Second sub-section
------------------

[**Exercise 2.1**]{#exercise:2.2.1 .pandoc-numbering-text .exercise}

[**Exercise 2.2**]{#exercise:2.2.2 .pandoc-numbering-text .exercise}

The prefix and name parts are composed of a letter followed by any number of letter, digit, . and - characters.

If the optional prefix and name parts are present, the identifier of the span element is set using the prefix and name parts.

Section
=======

Subsection
----------

Exercise -.+.#myprefix:myid

will be rendered as

Section
=======

Subsection
----------

[**Exercise 1.1**]{#myprefix:myid .pandoc-numbering-text .myprefix}

If the optional prefix part is present without the name part, the identifier of the span element is set using the prefix part followed by the full numbering of the paragraph.

Section
=======

Subsection
----------

Exercise -.+.#myprefix:

will be rendered as

Section
=======

Subsection
----------

[**Exercise 1.1**]{#myprefix:1.1.1 .pandoc-numbering-text .myprefix}

If the optional name part is present without the prefix part, the identifier of the span element is constructed using the auto-identifier of the category followed by a : character and by the name part
```
Section
=======

Subsection
----------

Exercise -.+.#myid
```
will be rendered as
```
Section
=======

Subsection
----------

[**Exercise 1.1**]{#exercise:myid .pandoc-numbering-text .exercise}
```
If there is no name and prefix parts, the identifier of the span element is constructed using the conversion of the description into an auto-identifier (category) followed by a : character and by the full numbering of the paragraph (see preceding example). For the auto-identifier conversion:
- all accents are removed
- characters which are not a letter, a digit or a - character are replaced by a - character
- all beginning characters which are not a letter are removed
- all letters are converted to lowercase

Referencing

The information generated by the numbering step can be used anywhere in the text for cross-referencing:

[text](#identifier "caption")

the %T characters are replaced by the title in the text and in the caption;
the %t characters are replaced by the title in lower case in the text and in the caption;
the %D characters are replaced by the description in the text and in the caption;
the %d characters are replaced by the description in lower case in the text and in the caption;
the %s characters are replaced by the section numbering in the text and in the caption;
the %g characters are replaced by the global numbering in the text and in the caption;
the %c characters are replaced by the current count in the text and in the caption;
the %p characters are replaced by the page number in the text and in the caption (work only for pdf format that use a LaTeX engine);
the %n and # characters are replaced by the local numbering in the text and in the caption;

List of things

If you want a listing of a particular category at the top of your document, you can add a listing-title entry in the metadata:

---
pandoc-numbering:
  exercise:
    general:
      listing-title: List of exercises
---
Exercise (The first exercise) #

Exercise (The second exercise) #

will be rendered as:

List of exercises {#list-of-exercises .pandoc-numbering-listing .exercise .unnumbered .unlisted}
=================

-   [[The first exercise]{.pandoc-numbering-entry
    .exercise}](#exercise:1)
-   [[The second exercise]{.pandoc-numbering-entry
    .exercise}](#exercise:2)

[**Exercise 1** *(The first exercise)*]{#exercise:1
.pandoc-numbering-text .exercise}

[**Exercise 2** *(The second exercise)*]{#exercise:2
.pandoc-numbering-text .exercise}

By default, an identifier is added to the listing title. It’s possible to change the identifier using a listing-identifier entry in the metadata:

---
pandoc-numbering:
  exercise:
    general:
      listing-title: List of exercises
      listing-identifier: myident
---
Exercise (The first exercise) #

Exercise (The second exercise) #

will be rendered as:

List of exercises {#myident .pandoc-numbering-listing .exercise .unnumbered .unlisted}
=================

-   [[The first exercise]{.pandoc-numbering-entry
    .exercise}](#exercise:1)
-   [[The second exercise]{.pandoc-numbering-entry
    .exercise}](#exercise:2)

[**Exercise 1** *(The first exercise)*]{#exercise:1
.pandoc-numbering-text .exercise}

[**Exercise 2** *(The second exercise)*]{#exercise:2
.pandoc-numbering-text .exercise}

It’s also possible not to have an identifier using the False value:

---
pandoc-numbering:
  exercise:
    general:
      listing-title: List of exercises
      listing-identifier: False
---
Exercise (The first exercise) #

Exercise (The second exercise) #

Default sectioning

If the sectioning part is empty, it is possible to use a default sectioning part defined in the meta-data block using the sectioning-levels key:

---
pandoc-numbering:
  ex:
    general:
      sectioning-levels: -.+.
---
Section
=======

Subsection
----------

Exercise #ex:

will be rendered as

Section
=======

Subsection
----------

[**Exercise 1.1**]{#ex:1.1.1 .pandoc-numbering-text .ex}

You can also use the first-section-level and last-section-level key (first section level to appear, last section level to appear):

---
pandoc-numbering:
  ex:
    general:
      sectioning-levels: -.+.
---

is equivalent to

---
pandoc-numbering:
  ex:
    general:
      first-section-level: 2
      last-section-level: 2
---

Use of cite shortcut notation

You can also use the @identifier notation. It creates a link with default text and default caption. If cite-shortcut: False is in the meta-data block for a given category, this feature is disabled.

Formatting

Basically:

the text displayed for a new numbering is **Category number** *(Title)* or **Category number**;
the link displayed for an automatic reference is Category number using the cite shortcut notation;
the entry in the table of contents is Category number (Category for LaTeX document) or Title.

These behaviors can be changed by adding metadata for a given category.

format-text-classic is for the text displayed (you can use special characters %D, %d, %s, %g, %n, #, %c)
format-text-title is for the text displayed when a title is present (you can use special characters %D, %d, %T, %t, %s, %g, %n, #, %c)
format-link-classicis for the link displayed using the cite shortcut notation (you can use special characters %D, %d, %s, %g, %n, #, %c, %p)
format-link-titleis for the link displayed when a title is present using the cite shortcut notation (you can use special characters %D, %d, %T, %t, %s, %g, %n, #, %c, %p)
format-caption-classic is for the text displayed in the captions (you can use special characters %D, %d, %s, %g, %n, # and %p for LaTeX)
format-caption-title is for the text displayed in the captions when a title is present (you can use special characters %D, %d, %T, %t, %s, %g, %n, # and %p for LaTeX)
format-entry-classic is for the entry displayed in the table of contents (you can use special characters %D, %d, %s, %g, %n, #)
format-entry-title is for the entry displayed in the table of contents when a title is present (you can use special characters %D, %d, %T, %t, %s, %g, %n, #)

By default these values are equal to

---
pandoc-numbering:
  exercise:
    standard:
      format-text-classic: '**%D %n**'
      format-text-title: '**%D %n** *(%T)*'
      format-link-classic: '%D %n'
      format-link-title: '%D %n (%T)'
      format-caption-classic: '%D %n'
      format-caption-title': '%D %n (%T)'
      format-entry-title': '%T'
      format-entry-classic': '%D %g'
    latex:
      format-text-classic: '**%D %n**'
      format-text-title: '**%D %n** *(%T)*'
      format-link-classic: '%D %n'
      format-link-title: '%D %n (%T)'
      format-caption-classic: '%D %n'
      format-caption-title: '%D %n (%T)'
      format-entry-title': '%T'
      format-entry-classic': '%D'
---

Classes

The classes added to the elements can be changed using the classes keyword in the meta.

---
pandoc-numbering:
  exercise:
    general:
      listing-title: List of exercises
      classes: [my-class1, my-class2]
---
Section
=======

Exercise (The first exercise) #

Exercise (The second exercise) #

See @exercise:1

will be rendered as:

List of exercises {.pandoc-numbering-listing .my-class1 .my-class2 .unnumbered .unlisted}
=================

-   [[The first exercise]{.pandoc-numbering-entry .my-class1
    .my-class2}](#exercise:1)
-   [[The second exercise]{.pandoc-numbering-entry .my-class1
    .my-class2}](#exercise:2)

Section
=======

[**Exercise 1** *(The first exercise)*]{#exercise:1
.pandoc-numbering-text .my-class1 .my-class2}

[**Exercise 2** *(The second exercise)*]{#exercise:2
.pandoc-numbering-text .my-class1 .my-class2}

See [[Exercise 1 (The first exercise)]{.pandoc-numbering-link .my-class1
.my-class2}](#exercise:1 "Exercise 1 (The first exercise)")

Example

Demonstration: Using pandoc-numbering-sample.txt as input gives output files in pdf, tex, html, epub and other formats.