How to make Lua filters available system-wide in Pandoc?

[kadykov]

I'm working on a Docker-based application that uses Pandoc Lua filters. My goal is to make the Lua filters available system-wide for all users in the container, not just for a single user.

Context

To my knowledge, Pandoc looks for resources (e.g., filters, templates) in the $XDG_DATA_HOME/pandoc/ directory. If $XDG_DATA_HOME is unset, it defaults to ~/.local/share/pandoc/.

Placing Lua filters in ~/.local/share/pandoc/filters/ works perfectly for a single user, but I need them to be accessible system-wide.

Attempts

1. I tried placing the filters in:

   • /usr/local/share/pandoc/filters/
   • /usr/share/pandoc/filters/

   However, Pandoc did not detect them.

2. In the Pandoc Dockerfiles repository they set globaly $XDG_DATA_HOME, but it could potentially break other tools.

3. Using the --data-dir option works when explicitly passed to Pandoc:

   pandoc --data-dir=/usr/local/share/pandoc ...

   But this approach requires every call of Pandoc to include the --data-dir option, which is inconvenient in some scenarios.

Question

Is there a recommended way to configure Pandoc to recognize a system-wide directory (e.g., /usr/local/share/pandoc/filters/) for Lua filters and other resources without relying on --data-dir for every call?

Any advice or best practices would be greatly appreciated!

[jgm]

You could try

alias 'mypandoc'='pandoc --data-dir=/usr/local/share/pandoc'

[bpj]

In /etc/bash.bashrc¹ assuming the bash shell and a typical Linux system if you want it to be system wide, so you'll have to edit it with something like sudo $EDITOR /etc/bash.bashrc

Footnotes

1. /etc/zshrc if you/any users are using the zsh shell (as I do! :-) ↩

[alerque]

Adding an alias is a useful hack, but I don't think it's all that could be desired.

I've run across a similar desire to provide filters to be used elsewhere and at this point there isn't a very ergonomic way. I do think their should be. In particular being able to package and distribute Lua filters via LuaRocks including dependencies would be especially convenient, and right now it can really only be done with some kludgey extra shenanigans.

I suggest this could be promoted from a discussion to a feature request.

[bpj]

Or even better a system wide defaults file which is applied in a system wide alias.

In /etc/bash.bashrc add

alias mypandoc='pandoc --defaults
/usr/local/share/pandoc/defaults.yaml'

Then sudo $EDITOR /usr/local/share/pandoc/defaults.yaml

where you add

# System wide data dir
data-dir: /usr/local/share/pandoc

# Filters which should be run every time by everyone
filters:
  - /usr/local/share/pandoc/filters/always.lua

# Metadata available to all users
metadata-files:
  - /usr/local/share/pandoc/metadata/common.yaml

# Whatever else could go in a defaults file

then in /usr/local/share/pandoc/metadata/common.yaml things which could be accessed in custom templates or filters

organization: Example
org-email: info@example.org
org-phone: 0123456789
org-website: 'https://example.org'

Don’t forget to set all necessary permissions!

@jgm I still think it would be a good idea for pandoc to apply

• $DATA_DIR/defaults/default.yaml
• $DATA_DIR/defaults/default-$FORMAT.yaml
• $DATA_DIR/metadata/default.yaml
• $DATA_DIR/metadata/default-$FORMAT.yaml

automatically before all other defaults/metadata files just like $DATA_DIR/templates/default.$FORMAT is used automatically with --standalone. That defaults file can then invoke other global defaults files as needed. I can open an issue for it if you think it is a good idea.

[alerque]

a system wide alias

I understand aliases, and they are great for interactive shell. The main trouble is they don't propagate to scripting environments and third party tools that call tools directly with no shell intermediary (much less an interactive one where aliases would be relevant).

[jgm]

Instead of an alias you could just make a shell script called pandoc that calls the actual pandoc executable but adds certain flags.

I see the point of the request, though. Feel free to open an issue if you like.