prefix-ids

title	author
Prefix-ids: add prefix to all identifiers in Pandoc document	Julien Dutant

Prefix-ids

Add prefix to all identifiers in Pandoc document. Consists of two filters:

• crossref-prefix-ids: prefix pandoc-crossref identifiers and the corresponding citation links
• prefix-ids: prefix standard identifiers and internal links to them

The former should be applied before pandoc-crossref is applied. The second is to be applied after other identifier/link generating filters are applied, notably after citeproc.

v0.1. Copyright: © 2021 Julien Dutant julien.dutant@kcl.ac.uk License: MIT - see LICENSE file for details.

Description

Internal links within a Pandoc document, including those generated by citations with Citeproc, rely on identifiers. To avoid clashes when several documents are put together, this filter:

1. adds a custom (or random) prefix to all elements with an identifier within a document's body
2. fixes any internal links using those identifiers

It is best used after filters that add or modify links.

Note. Pandoc's id_prefix option does something similar but only for HTML and DocBook output. This filter applies the prefix within the Pandoc AST document, making it suitable for inclusion within wider pandoc documents, directly or via json output.

On the other hand, Pandoc's id_prefix option covers footnote links in HTML outputs, and this function can't control them. So this function is best used for non-HTML only.

The filter can be used together with Pandoc-crossref.

Usage

The filter is loaded with the Pandoc -L or --lua-filter option.

pandoc -L path/to/prefix-ids.lua source.md -o output.html

If the filter is in Pandoc's $DATADIR there is no need to give its path. See [Pandoc's manual[ (https://pandoc.org/MANUAL.html#general-options) for details.

If using Pandoc-crossref and targeting LaTeX output, the crossref-prefix filter should be used to, placed before crossref. A standard order would then be crossref-prefix, pandoc-crossref, citeproc and then predix-ids:

pandoc -L crossref-prefix.lua -F pandoc-crossref --citeproc -L prefix-ids.lua  source.md -o output.html

If using Pandoc-crossref but not

These can be specified in a defaults yaml file, called with pandoc -d defaults.yaml source.md -o output.html:

filters:
- crossref-prefix.lua
- pandoc-crossref
- citeproc
- prefix-ids.lua

Options

A custom prefix can be specified in the document metadata:

prefix-ids:
  prefix: 'my prefix'

If no prefix is specified, the filter will use a random 40-char string of letters and numbers (sha1 of the document's body).

By default the filter handles [Pandoc-crossref] (https://lierdakil.github.io/pandoc-crossref/) syntax: an identifier #fig:figure1 becomes #fig:prefixfigure1. To disable this behaviour set the pandoc-crossref suboption to false:

prefix-ids:
  pandoc-crossref: false

Aliases of these options are provided to allow you to set them from the command line: prefixs-ids-prefix and prefix-ids-pandoc-crossref. Use the Pandoc option -M (--metadata) to do so:

pandoc -L prefix-ids.lua sample.md -o out.html -M prefix-ids-pandoc-crossref=false

If both standard and alias are provided, the latter prevails.

Warning

The filter doesn't handle identifiers and links situated in the document's metadata, e.g. in the abstract or thanks field.