lua-env Example

Quarto Extension

Author

Introduction

lua-env is an extension for Quarto to provide access to LUA objects as metadata.

This extension gives you access to the quarto object and several Pandoc LUA internal objects using shortcodes.

Installation

quarto add mcanouil/quarto-lua-env@1.5.0

This will install the extension under the _extensions subdirectory.

If you’re using version control, you will want to check in this directory.

Usage

Add the following to your YAML header:

Old (<1.8.21):
```
filters:
  - quarto
  - lua-env
```

New (>=1.8.21):

filters:
  - path: lua-env
    at: post-quarto

This enables access to LUA objects using two shortcode formats:

/home/runner/work/quarto-lua-env/quarto-lua-env/example.qmd - Direct access via shortcode.
/home/runner/work/quarto-lua-env/quarto-lua-env/example.qmd - Access via metadata.

Available LUA Objects

The following LUA objects are available as metadata:

lua-env:
  quarto: "quarto"
  pandoc:
    PANDOC_STATE: "PANDOC_STATE"
    FORMAT: "FORMAT"
    PANDOC_READER_OPTIONS: "PANDOC_READER_OPTIONS"
    PANDOC_WRITER_OPTIONS: "PANDOC_WRITER_OPTIONS"
    PANDOC_VERSION: "PANDOC_VERSION"
    PANDOC_API_VERSION: "PANDOC_API_VERSION"
    PANDOC_SCRIPT_FILE: "PANDOC_SCRIPT_FILE"

See Pandoc LUA API - Global Variables for more information about Pandoc global variables.

Shortcodes

Quarto

{{< lua-env quarto.doc.input_file >}}

/home/runner/work/quarto-lua-env/quarto-lua-env/example.qmd

{{< meta lua-env.quarto.doc.input_file >}}

/home/runner/work/quarto-lua-env/quarto-lua-env/example.qmd

Pandoc

{{< lua-env pandoc.PANDOC_VERSION >}}

3.8.3

{{< meta lua-env.pandoc.PANDOC_VERSION >}}

3.8.3

{{< lua-env pandoc.FORMAT >}}

html

{{< meta lua-env.pandoc.FORMAT >}}

html

JSON Export

This document is configured to export the lua-env metadata to a JSON file, with the quarto._quarto branch removed and sensitive filesystem paths redacted.

extensions:
  lua-env:
    json: true
    json-exclude:
      - quarto._quarto
    json-exclude-sensitive: true
    json-warn-on-server: true

By default, no JSON file is written (json: false). To enable JSON export, set json: true (writes to lua-env.json) or provide a custom file path.

JSON export schema

The exported JSON is an object with two top-level keys, pandoc and quarto.

{
  "pandoc": {
    "FORMAT": "html",
    "PANDOC_API_VERSION": "1.23",
    "PANDOC_VERSION": "3.6.3",
    "PANDOC_READER_OPTIONS": { },
    "PANDOC_WRITER_OPTIONS": { },
    "PANDOC_STATE": { }
  },
  "quarto": {
    "version": [1, 7, 32],
    "doc": { },
    "project": { },
    "log": { },
    "json": { }
  }
}

Container shapes mirror the live Pandoc/Quarto objects. Functions and userdata are dropped. Empty branches are omitted.

Filtering options

json-include: array of dot-separated paths to keep (e.g. pandoc.FORMAT). Everything outside the listed paths is omitted.
json-exclude: array of dot-separated paths to drop, applied after the include whitelist.
json-exclude-sensitive (default true): redacts built-in sensitive paths that expose host filesystem layout, namely quarto.doc.input_file, quarto.doc.output_file, quarto.project.directory, quarto.project.output_directory, and pandoc.PANDOC_SCRIPT_FILE. Set to false to include them.
json-warn-on-server (default true): emits a warning when JSON export is enabled in a CI or server context (CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, TRAVIS, JENKINS_URL, BUILDKITE, TF_BUILD). Set to false to silence.

For example, to export only the active Pandoc format and Quarto version:

extensions:
  lua-env:
    json: true
    json-include:
      - pandoc.FORMAT
      - quarto.version

To remove a noisy branch while keeping everything else:

extensions:
  lua-env:
    json: true
    json-exclude:
      - quarto._quarto

To use a custom output filename:

extensions:
  lua-env:
    json: "custom-output.json"