Skip to content

A pandoc Lua filter for referencing metadata values within a document, thus applying variable substitution

License

Notifications You must be signed in to change notification settings

cdivita/pandoc-curly-switch

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

22 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Works with pandoc

curly-switch

A pandoc Lua filter for referencing metadata values within a document, thus applying variable substitution.

Referencing variables

Every document metadata, defined within the YAML metadata block or through --metadata/--metadata-file arguments, can be referenced as variable within the document itself. During the conversion, the variables placeholders are replaced with their effective values.

The following syntax is supported for defining variables placeholders:

  • ${...}, the curly brackets syntax
  • !...!, the exclamation marks syntax

Variable can be referenced using an object-like notation, using any of the supported syntax. For example, having the following YAML metadata block:

github:
  organization: https://github.com/cdivita
  url: ${github.organization}/pandoc-curly-switch
filter:
  name: curly-switch
  language: lua
  license:
    type: Apache License, 2.0
  developers:
    - name: Claudio Di Vita
      url: ${github.organization}

The filter's name can be referenced through ${filter.name} or !filter.name!.

Variables are replaced also within metadata block itself and list elements can be referenced using 1-based indexes. For example:

  • ${github.url} is replaced with https://github.com/cdivita/pandoc-curly-switch
  • ${filter.developers.1.name} is replaced with Claudio Di Vita

The exclamation marks syntax (!...!) is suggested within LaTeX blocks, because it doesn't clash with math mode and doesn't break syntax highlighting tools.

Potential issues with tex_math_dollars extension

When using the curly brackets syntax (${...}), since the tex_math_dollars extension is enabled by default, depending on the expression used, due to inaccurate metadata parsing, issues can be experienced.

To avoid such issues, the following options are available:

  • Escape the $ character with a backslash \$: for example, \${my.variable}
  • Disable the tex_math_dollars extension using the -f/--from: -f markdown-tex_math_dollars

Installation

As any pandoc Lua filter, curly-switch can be used without special installation, just by passing the respective .lua file path to pandoc using the --lua-filter/-L argument.

User-global installation is possible by placing a filter in within the filters directory of pandoc's user data directory. This allows to use the filters just by using the filename, without having to specify the full file path.

On Mac and Linux, the filter can be installed through the command line using a single instruction:

CURLY_SWITCH=curly-switch.lua curl -LSs -o $(pandoc --version | sed -n "s/^.*User data directory:\s*\(\S*\).*$/\1/p")/${CURLY_SWITCH} https://raw.githubusercontent.com/cdivita/pandoc-curly-switch/main/${CURLY_SWITCH}

About

A pandoc Lua filter for referencing metadata values within a document, thus applying variable substitution

Topics

Resources

License

Stars

Watchers

Forks

Languages