Reference

Every option the lua-env extension accepts.

The complete lua-env configuration: enabling the filter, the shortcode, the metadata tree it publishes, and the JSON export with its filters.

Enabling the filter

The shortcode reads metadata the filter collects, so the filter has to run first.

filters:
  - lua-env

The extension registers the filter at pre-quarto, before Quarto expands shortcodes, so the entry point never has to be named here.

Shortcode

{{< lua-env <path> >}}
The argument of the lua-env shortcode.
Argument Type Required Description
path string Yes A dot-separated path into the collected metadata, such as quarto.version or pandoc.FORMAT.

Everything the extension collects also sits under the lua-env metadata key, so Quarto’s own shortcode reaches the same values:

{{< meta lua-env.quarto.version >}}

What is published

Two branches, mirroring the live Lua objects.

The metadata tree.
Branch Contents
pandoc FORMAT, PANDOC_VERSION, PANDOC_API_VERSION, PANDOC_STATE, PANDOC_READER_OPTIONS, PANDOC_WRITER_OPTIONS, PANDOC_SCRIPT_FILE.
quarto version, doc, project, log, json, and the rest of the quarto table.

The Pandoc names are documented under Global Variables in the Pandoc manual.

Functions and userdata cannot be represented as metadata and are dropped. Branches left empty by that are pruned.

JSON export

JSON export options.
Option Type Default Description
json boolean or string false true writes lua-env.json; a string writes that path; false writes nothing.
json-include string or array Dot-separated paths to keep. Anything outside them is omitted. Omit the option to keep everything.
json-exclude string or array Dot-separated paths to drop, applied after json-include.
json-exclude-sensitive boolean true Drops the paths listed below, leaving nothing in their place.
json-warn-on-server boolean true Warns when the export runs in a CI or server context.

A relative json path is resolved against the directory of the document being rendered, not the project root and not the output directory. json: true therefore drops lua-env.json next to the source file, where it is a build artefact to ignore rather than something the site publishes.

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

json accepts a real YAML boolean, its quoted string form, or a path.

Redacted paths

With json-exclude-sensitive left at true, these are removed because they describe the machine that ran the render rather than the document:

  • quarto.doc.input_file
  • quarto.doc.output_file
  • quarto.project.directory
  • quarto.project.output_directory
  • pandoc.PANDOC_SCRIPT_FILE
Warning

Turning that off writes absolute paths from the build machine into a file, and a published site will serve it. The warning under json-warn-on-server exists for the same reason: an export that is useful on a laptop is usually a leak in CI.

json-warn-on-server triggers on any of CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, TRAVIS, JENKINS_URL, BUILDKITE, and TF_BUILD.

Shape of the file

{
  "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": { },
    "_quarto": { }
  }
}

Limitations

  • The filter must be enabled explicitly; installing the extension is not enough.
  • Values are collected as the filter runs, so a shortcode reads the state at that point rather than at the end of the render.
  • Anything that is a function or userdata in Lua has no metadata equivalent and does not appear.
Back to top