Merge pull request #13246 from quarto-dev/feature/lua-api-shortcodes

new Lua APIs for programmatic access to var and meta shortcode results

Author: cscheid

news/changelog-1.8.md

@@ -76,12 +76,13 @@ All changes included in 1.8:
 
 - ([#12615](https://github.com/quarto-dev/quarto-cli/pull/12615)): Adds `algorithm` to theorem environments. (author: @jeremy9959)
 
-## Lua Filters
+## Lua Filters and API
 
 - ([#12727](https://github.com/quarto-dev/quarto-cli/issues/12727)): Do not crash in the presence of malformed tabset contents.
 - ([#12806](https://github.com/quarto-dev/quarto-cli/pull/12806)): Use pandoc APIs to handle codepage conversion on Windows.
 - ([#12811](https://github.com/quarto-dev/quarto-cli/pull/12811)): Add support for YouTube Shorts in `video` shortcode.
 - ([#13128](https://github.com/quarto-dev/quarto-cli/issues/13128)): Meta shortcode could crash on bad input.
+- ([#13246](https://github.com/quarto-dev/quarto-cli/pull/13246)): Add `quarto.variables.get()` and `quarto.metadata.get()` APIs.
 
 ## Commands
 

src/resources/lua-types/quarto/metadata.lua

@@ -0,0 +1,13 @@
+---@meta
+
+quarto.metadata = {}
+
+--[[
+Return the value of a metadata entry in Quarto metadata as a pandoc.MetaValue.
+Return nil if the key (or any of its subcomponents) are missing.
+
+This is the Lua equivalent of the {{< meta key >}} shortcode in Quarto documents.
+]]
+---@param key string metadata key, possibly with nested keys separated by dots
+---@return pandoc.MetaValue | nil
+function quarto.metadata.get(key) end

src/resources/lua-types/quarto/variables.lua

@@ -0,0 +1,12 @@
+---@meta
+
+quarto.variables = {}
+
+--[[
+Return the value of a variable in _variables.yml as a string, or nil if name is missing.
+
+This is the Lua equivalent of the {{< var name >}} shortcode in Quarto documents.
+]]
+---@param name string name of variable
+---@return string | nil
+function quarto.variables.get(name) end

src/resources/pandoc/datadir/init.lua

@@ -1031,6 +1031,20 @@ quarto = {
           end
       end,
   },
+  metadata = {
+    get = function(key)
+      return option(key, nil)
+    end
+  },
+  variables = {
+    get = function(name)
+      local value = var(name, nil)
+      if value then
+         value = pandoc.utils.stringify(value)
+      end
+      return value
+    end
+  }
 }
 
 -- alias old names for backwards compatibility

tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/.gitignore

@@ -0,0 +1,3 @@
+/.quarto/
+
+/.luarc.json

tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_metadata.yml

@@ -0,0 +1 @@
+meta_from_metadata: value_from_metadata

tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_quarto.yml

@@ -0,0 +1,21 @@
+project:
+  type: website
+
+website:
+  title: "test-lua-shortcode-apis"
+  navbar:
+    left:
+      - href: index.qmd
+        text: Home
+      - about.qmd
+
+format:
+  html:
+    theme:
+      - cosmo
+      - brand
+    css: styles.css
+    toc: true
+
+
+

tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_variables.yml

@@ -0,0 +1 @@
+var1: var_value

tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/about.qmd

@@ -0,0 +1,5 @@
+---
+title: "About"
+---
+
+About this site

tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/index.qmd

@@ -0,0 +1,26 @@
+---
+title: "test-lua-shortcode-apis"
+meta1: meta_value
+meta2: 2
+meta3:
+  - foo
+  - bar
+meta4:
+  key1: value1
+  key2: value2
+filters:
+  - set_span_values.lua
+_quarto:
+  tests:
+    html:
+      ensureFileRegexMatches:
+        -
+          - meta_value
+          - var_value
+---
+
+This is a Quarto website.
+
+To learn more about Quarto websites visit <https://quarto.org/docs/websites>.
+
+[]{#span1}, []{#span2}