diff --git a/news/changelog-1.8.md b/news/changelog-1.8.md index 4fd9b260b25..9f5bd6da0bf 100644 --- a/news/changelog-1.8.md +++ b/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 diff --git a/src/resources/lua-types/quarto/metadata.lua b/src/resources/lua-types/quarto/metadata.lua new file mode 100644 index 00000000000..cfc4e565281 --- /dev/null +++ b/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 diff --git a/src/resources/lua-types/quarto/variables.lua b/src/resources/lua-types/quarto/variables.lua new file mode 100644 index 00000000000..1b2016b8bb8 --- /dev/null +++ b/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 diff --git a/src/resources/pandoc/datadir/init.lua b/src/resources/pandoc/datadir/init.lua index 57da17d70b7..d9639b02e1c 100644 --- a/src/resources/pandoc/datadir/init.lua +++ b/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 diff --git a/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/.gitignore b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/.gitignore new file mode 100644 index 00000000000..ded205c8129 --- /dev/null +++ b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/.gitignore @@ -0,0 +1,3 @@ +/.quarto/ + +/.luarc.json diff --git a/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_metadata.yml b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_metadata.yml new file mode 100644 index 00000000000..091aac5152e --- /dev/null +++ b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_metadata.yml @@ -0,0 +1 @@ +meta_from_metadata: value_from_metadata \ No newline at end of file diff --git a/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_quarto.yml b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_quarto.yml new file mode 100644 index 00000000000..4aa7a667c4e --- /dev/null +++ b/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 + + + diff --git a/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_variables.yml b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_variables.yml new file mode 100644 index 00000000000..ffce36b3afa --- /dev/null +++ b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/_variables.yml @@ -0,0 +1 @@ +var1: var_value \ No newline at end of file diff --git a/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/about.qmd b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/about.qmd new file mode 100644 index 00000000000..07c5e7f9d13 --- /dev/null +++ b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/about.qmd @@ -0,0 +1,5 @@ +--- +title: "About" +--- + +About this site diff --git a/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/index.qmd b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/index.qmd new file mode 100644 index 00000000000..7ef8c0e2807 --- /dev/null +++ b/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 . + +[]{#span1}, []{#span2} \ No newline at end of file diff --git a/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/set_span_values.lua b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/set_span_values.lua new file mode 100644 index 00000000000..42439920bfa --- /dev/null +++ b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/set_span_values.lua @@ -0,0 +1,24 @@ +function Span(span) + -- print(quarto.variables.get("var1")) + -- print(quarto.metadata.get("meta1")) + if span.identifier == "span1" then + span.content = quarto.utils.string_to_inlines( + pandoc.utils.stringify(quarto.variables.get("var1"))) + return span + elseif span.identifier == "span2" then + span.content = quarto.utils.string_to_inlines( + pandoc.utils.stringify(quarto.metadata.get("meta1"))) + return span + end +end + +function Pandoc(doc) + local function get_meta(key) + return pandoc.utils.stringify(quarto.metadata.get(key)) + end + assert(type(quarto.metadata.get("meta3")) == "table") + assert(get_meta("meta2") == "2") + assert(get_meta("meta4.key1") == "value1") + assert(get_meta("meta4.key2") == "value2") + assert(get_meta("meta_from_metadata") == "value_from_metadata") +end \ No newline at end of file diff --git a/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/styles.css b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/styles.css new file mode 100644 index 00000000000..2ddf50c7b42 --- /dev/null +++ b/tests/docs/smoke-all/2025/08/19/test-lua-shortcode-apis/styles.css @@ -0,0 +1 @@ +/* css styles */