Merge pull request #12421 from quarto-dev/feature/12326

lua - new quarto.shortcode API

Author: cscheid

news/changelog-1.7.md

@@ -109,6 +109,7 @@ All changes included in 1.7:
 - ([#11896](https://github.com/quarto-dev/quarto-cli/pull/11896)): fix `\f` (`{{< pagebreak >}}`) form feed character not valid in PowerPoint (`pptx`).
 - ([#11664](https://github.com/quarto-dev/quarto-cli/issues/11664)): `lipsum` shortcode is no longer randomly generated by default, use `{{< lipsum random=true >}}` to restore randomness.
 - ([#11379](https://github.com/quarto-dev/quarto-cli/issues/11379)): Add `version` shortcode to display the current Quarto version.
+- ([#12326](https://github.com/quarto-dev/quarto-cli/issues/12326)): Add `quarto.shortcode.*` API entry points for shortcode developers.
 
 ## Quarto Lua API
 

src/resources/filters/quarto-pre/shortcodes-handlers.lua

@@ -59,19 +59,7 @@ end
 
 local handlers = {}
 
-local function read_arg(args, n)
-  local arg = args[n or 1]
-  local varName
-  if arg == nil then
-    return nil
-  end
-  if type(arg) ~= "string" then
-    varName = inlinesToString(arg)
-  else
-    varName = arg
-  end
-  return varName
-end
+local read_arg = quarto.shortcode.read_arg
 
 function initShortcodeHandlers()
 
@@ -121,16 +109,7 @@ function initShortcodeHandlers()
 
     local warn_bad_brand_command = function()
       warn("Unknown brand command " .. brandCommand .. " specified in a brand shortcode.")
-      if context == "block" then
-        return pandoc.Blocks { pandoc.Strong({pandoc.Str("?brand:" .. table.concat(args, " "))}) }
-      elseif context == "inline" then
-        return pandoc.Inlines { pandoc.Strong({pandoc.Str("?brand:" .. table.concat(args, " "))}) }
-      elseif context == "text" then
-        return "?brand:" .. table.concat(args, " ")
-      else
-        warn("Unknown context for brand shortcode error: " .. context)
-        return { }
-      end
+      return quarto.shortcode.error_output("brand", args, context)
     end
 
     if brandCommand == "color" then 
@@ -202,19 +181,19 @@ function handlerForShortcode(shortCode)
 end
 
 -- Implements reading values from envrionment variables
-function handleEnv(args)
+function handleEnv(args, _kwargs, _meta, _raw_args, context)
   if #args > 0 then
     -- the args are the var name
     local varName = read_arg(args)
     local defaultValue = read_arg(args, 2)
 
     -- read the environment variable
-    local envValue = os.getenv(varName) or defaultValue
+    local envValue = varName and os.getenv(varName) or defaultValue
     if envValue ~= nil then
       return { pandoc.Str(envValue) }  
     else 
       warn("Unknown variable " .. varName .. " specified in an env Shortcode.")
-      return { pandoc.Strong({pandoc.Str("?env:" .. varName)}) } 
+      return quarto.shortcode.error_output("env", args, context)
     end
   else
     -- no args, we can't do anything
@@ -226,10 +205,10 @@ end
 -- as {{< meta title >}}
 -- or {{< meta key.subkey.subkey >}}
 -- This only supports emitting simple types (not arrays or maps)
-function handleMeta(args) 
+function handleMeta(args, _kwargs, _meta, _raw_args, context) 
   if #args > 0 then
     -- the args are the var name
-    local varName = read_arg(args)
+    local varName = read_arg(args) or ""
 
     -- strip quotes if present
     -- works around the real bug that we don't have
@@ -247,7 +226,7 @@ function handleMeta(args)
       return processValue(optionValue, varName, "meta")
     else 
       warn("Unknown meta key " .. varName .. " specified in a metadata Shortcode.")
-      return { pandoc.Strong({pandoc.Str("?meta:" .. varName)}) } 
+      return { pandoc.Strong(pandoc.Inlines {pandoc.Str("?meta:" .. varName)}) } 
     end
   else
     -- no args, we can't do anything
@@ -259,7 +238,7 @@ end
 -- as {{< var title >}}
 -- or {{< var key.subkey.subkey >}}
 -- This only supports emitting simple types (not arrays or maps)
-function handleVars(args) 
+function handleVars(args, _kwargs, _meta, _raw_args, context) 
   if #args > 0 then
     -- the args are the var name
     local varName = read_arg(args)
@@ -270,7 +249,7 @@ function handleVars(args)
       return processValue(varValue, varName, "var")
     else 
       warn("Unknown var " .. varName .. " specified in a var shortcode.")
-      return { pandoc.Strong({pandoc.Str("?var:" .. varName)}) } 
+      return quarto.shortcode.error_output("var", args, context)
     end
 
   else
@@ -291,10 +270,10 @@ function processValue(val, name, t)
       return processValue(val[1])
     else
       warn("Unsupported type '" .. pandoc.utils.type(val)  .. "' for key " .. name .. " in a " .. t .. " shortcode.")
-      return { pandoc.Strong({pandoc.Str("?invalid " .. t .. " type:" .. name)}) }         
+      return { pandoc.Strong(pandoc.Inlines { pandoc.Str("?invalid " .. t .. " type:" .. name) } ) }
     end
   else 
-    return { pandoc.Str( tostring(val) ) }  
+    return { pandoc.Str( tostring(val) ) }
   end
 end
 
@@ -329,7 +308,7 @@ function handlePagebreak()
     return pandoc.RawBlock('context', pagebreak.context)
   else
     -- fall back to insert a form feed character
-    return pandoc.Para{pandoc.Str '\f'}
+    return pandoc.Para( pandoc.Inlines { pandoc.Str '\f'} )
   end
 
 end

src/resources/lua-types/pandoc/blocks.lua

@@ -33,7 +33,7 @@ pandoc.Blocks = {}
 Create a blocks list 
 ]]
 ---@param blocks pandoc.Block|pandoc.List Block or list of blocks
----@return pandoc.List 
+---@return pandoc.Blocks 
 function pandoc.Blocks(blocks) end
 
 

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

@@ -0,0 +1,23 @@
+---@meta
+
+quarto.shortcode = {}
+
+--[[
+Read the `n`-th shortcode argument from the passed `args` table.
+]]
+---@param args string[] arguments from the handler
+---@param n number|nil index of the argument to read (default: 1)
+---@return string|nil
+function quarto.shortcode.read_arg(args, n) end
+
+--[[
+Produce output for a shortcode that failed to execute properly.
+
+This is useful for shortcode developers to provide error output
+consistent with how Quarto shortcodes provide error output.
+]]
+---@param name string Name of the shortcode
+---@param message_or_args string[]|string shortcode args or optional error message to display
+---@param context "block"|"inline"|"text" context of the shortcode
+---@return pandoc.Blocks|pandoc.Inlines|string
+function quarto.shortcode.error_output(name, message_or_args, context) end

src/resources/pandoc/datadir/_utils.lua

@@ -97,7 +97,7 @@ function tdump (tbl, raw)
     for k, v in pairsByKeys(tbl, typesThenValues) do
       if shouldPrint(k, v, tbl) then
         empty = false
-        formatting = indentStr .. "  " .. k .. ": "
+        local formatting = indentStr .. "  " .. k .. ": "
         v = asLua(v)
         if type(v) == "table" or type(v) == "userdata" and v.is_emulated then
           printInner(formatting)

src/resources/pandoc/datadir/init.lua

@@ -2139,7 +2139,38 @@ quarto = {
   config = {
     cli_path = function() return param('quarto-cli-path', nil) end,
     version = function() return version() end
-  }
+  },
+  shortcode = {
+      read_arg = function (args, n)
+         local arg = args[n or 1]
+         local varName
+         if arg == nil then
+            return nil
+         end
+         if type(arg) ~= "string" then
+            varName = inlinesToString(arg)
+         else
+            varName = arg --[[@as string]]
+         end
+         return varName
+      end,
+      error_output = function (shortcode, message_or_args, context)
+         if type(message_or_args) == "table" then
+            message_or_args = table.concat(message_or_args, " ")
+         end
+         local message = "?" .. shortcode .. ":" .. message_or_args
+         if context == "block" then
+            return pandoc.Blocks { pandoc.Strong( pandoc.Inlines { pandoc.Str(message) } ) }
+          elseif context == "inline" then
+            return pandoc.Inlines { pandoc.Strong( pandoc.Inlines { pandoc.Str(message) } ) }
+          elseif context == "text" then
+            return message
+          else
+            warn("Unknown context for " .. shortcode .. " shortcode error: " .. context)
+            return { }
+          end
+      end,
+  },
 }
 
 -- alias old names for backwards compatibility

tests/docs/shortcodes/custom.qmd

@@ -5,3 +5,7 @@ shortcodes:
 ---
 
 {{< shorty _bringit_ >}}
+
+{{< shorty error >}}
+
+{{< shorty error_args >}}

tests/docs/shortcodes/shorty.lua

@@ -2,7 +2,13 @@
 
 return {
   shorty = function(args)
-    return pandoc.Strong(args[1])
+    if args[1] == "error_args" then
+      return quarto.shortcode.error_output("shorty", args, "inline")
+    elseif args[1] == "error" then
+      return quarto.shortcode.error_output("shorty", "error message", "inline")
+    else
+      return pandoc.Strong(args[1])
+    end
   end
 }
 

tests/smoke/shortcodes/shortcodes-core.test.ts

@@ -20,8 +20,10 @@ const outputCustom = outputForInput(inputCustom, "html");
 testRender(inputCustom, "html", false, [
   ensureFileRegexMatches(outputCustom.outputPath, [
     /<strong>_bringit_<\/strong>/,
+    /\?shorty:error_args/,
+    /\?shorty:error message/,
   ], [
-    /\?shorty/,
+    /\?shorty:_bringit_/,
   ]),
 ]);