search

pandoc / lua-filters

A collection of lua filters for pandoc
MIT License
600 stars 165 forks source link

shortcodes filter #231

Closed jjallaire closed 2 years ago

jjallaire commented 2 years ago

Shortcodes are a feature of Quarto implemented as a Lua filter that @nichtich asked us to factor out and contribute here (https://github.com/quarto-dev/quarto-cli/issues/904) so that they can be used outside of Quarto.

Shortcodes are a form of parameterized macro substitution, with syntax based on that already used by Hugo shortcodes. For example, the following shortcode prints the title from document metadata:

{{< meta title >}}

Shortcodes can return an inline or block element (or list of either) and can be used in both inline and block contexts (the results are normalized as appropriate).

The shortcodes.lua filter supports several shortcodes natively:

Shortcode Description
meta Print value from document metadata
env Print system environment variable
pagebreak Insert a native page-break

In addition, you can create custom shortcodes in Lua (see details in README.md).

jjallaire commented 2 years ago

Discussing this w/ @tarleb he pointed out that there is some debate about how these filters should be aggregated (repo w/ embedded source code as is now, list of links, etc.): https://github.com/pandoc/lua-filters/issues/207. I'll close this PR for now pending resolution of that discussion (happy to contribute this in whatever fashion makes after there is more clarity)

tarleb commented 2 years ago

For reference: The filter has been published at https://github.com/quarto-dev/quarto-shortcodes.