lua - create quarto.format API

news/changelog-1.5.md

@@ -158,6 +158,7 @@ All changes included in 1.5:
 - ([#9394](https://github.com/quarto-dev/quarto-cli/issues/9394)): Make `template` a required field in the `about` schema.
 - ([#9426](https://github.com/quarto-dev/quarto-cli/issues/9426)): Update `crossref.lua` filter to avoid crashes and hangs in documents with custom AST nodes.
 - ([#9492](https://github.com/quarto-dev/quarto-cli/issues/9492)): Improve performance of `quarto preview` when serving resource files of the following formats: HTML, PDF, DOCX, and plaintext.
+- ([#9527](https://github.com/quarto-dev/quarto-cli/pull/9527)): Add `quarto.format` and `quarto.format.typst` to Quarto's public Lua filter API.
 - Add support for `{{< lipsum >}}` shortcode, which is useful for emitting placeholder text. Provide a specific number of paragraphs (`{{< lipsum 3 >}}`).
 - Resolve data URIs in Pandoc's mediabag when rendering documents.
 - Increase v8's max heap size by default, to avoid out-of-memory errors when rendering large documents (also cf. https://github.com/denoland/deno/issues/18935).

src/resources/filters/customnodes/callout.lua

@@ -695,9 +695,9 @@ end, function(callout)
     title = pandoc.Plain(displayName(callout.type))
   end
 
-  local typst_callout = typst_function_call("callout", { 
-    { "body", as_typst_content(callout.content) },
-    { "title", as_typst_content(title) },
+  local typst_callout = _quarto.format.typst.function_call("callout", { 
+    { "body", _quarto.format.typst.as_typst_content(callout.content) },
+    { "title", _quarto.format.typst.as_typst_content(title) },
     { "background_color", pandoc.RawInline("typst", background_color) },
     { "icon_color", pandoc.RawInline("typst", icon_color) },
     { "icon", pandoc.RawInline("typst", "" .. icon .. "()")}

src/resources/filters/modules/typst.lua

@@ -0,0 +1,48 @@
+-- typst.lua
+-- Copyright (C) 2024 Posit Software, PBC
+
+-- helpers for working with typst in filters
+-- this module is exposed as quarto.format.typst
+
+local function _main()
+  local function typst_function_call(name, params)
+    local result = pandoc.Blocks({})
+    result:insert(pandoc.RawInline("typst", "#" .. name .. "("))
+    local function add(v)
+      if type(v) == "userdata" or type(v) == "table" then
+        result:extend(quarto.utils.as_blocks(v) or {})
+      else
+        result:extend(quarto.utils.as_blocks({pandoc.utils.stringify(v)}) or {})
+      end
+    end
+    -- needs to be array of pairs because order matters for typst
+    for i, pair in ipairs(params) do
+      local k = pair[1]
+      local v = pair[2]
+      if v ~= nil then
+        result:insert(pandoc.RawInline("typst", k .. ": "))
+        add(v)
+        result:insert(pandoc.RawInline("typst", ", "))
+      else
+        add(k)
+      end
+    end
+    result:insert(pandoc.RawInline("typst", ")"))
+    return pandoc.Div(result)
+  end
+
+  local function as_typst_content(content)
+    local result = pandoc.Blocks({})
+    result:insert(pandoc.RawInline("typst", "[\n"))
+    result:extend(quarto.utils.as_blocks(content) or {})
+    result:insert(pandoc.RawInline("typst", "]\n"))
+    return result
+  end
+
+  return {
+    function_call = typst_function_call,
+    as_typst_content = as_typst_content
+  }
+end
+
+return _main()

src/resources/filters/quarto-post/typst.lua

@@ -3,39 +3,11 @@
 --
 -- renders AST nodes to Typst
 
-function typst_function_call(name, params)
-  local result = pandoc.Blocks({})
-  result:insert(pandoc.RawInline("typst", "#" .. name .. "("))
-  local function add(v)
-    if type(v) == "userdata" or type(v) == "table" then
-      result:extend(quarto.utils.as_blocks(v) or {})
-    else
-      result:extend(quarto.utils.as_blocks({pandoc.utils.stringify(v)}) or {})
-    end
-  end
-  -- needs to be array of pairs because order matters for typst
-  for i, pair in ipairs(params) do
-    local k = pair[1]
-    local v = pair[2]
-    if v ~= nil then
-      result:insert(pandoc.RawInline("typst", k .. ": "))
-      add(v)
-      result:insert(pandoc.RawInline("typst", ", "))
-    else
-      add(k)
-    end
-  end
-  result:insert(pandoc.RawInline("typst", ")"))
-  return pandoc.Div(result)
-end
-
-function as_typst_content(content)
-  local result = pandoc.Blocks({})
-  result:insert(pandoc.RawInline("typst", "[\n"))
-  result:extend(quarto.utils.as_blocks(content) or {})
-  result:insert(pandoc.RawInline("typst", "]\n"))
-  return result
-end
+-- FIXME Ideally this would go directly on init.lua, but
+-- the module path set up doesn't appear to be working there.
+
+local typst = require("modules/typst")
+_quarto.format.typst = typst
 
 function render_typst()
   if not _quarto.format.isTypstOutput() then
@@ -94,8 +66,8 @@ function render_typst()
         if el.classes:includes("unlisted") then
           params:insert({"outlined", false})
         end
-        params:insert({as_typst_content(el.content)})
-        return typst_function_call("heading", params)
+        params:insert({_quarto.format.typst.as_typst_content(el.content)})
+        return _quarto.format.typst.function_call("heading", params)
       end,
     }
   }

src/resources/lua-types/quarto/format/typst.lua

@@ -0,0 +1,19 @@
+---@meta
+
+quarto.format.typst = {}
+
+--[[
+Create a node that represents a typst function call.
+]]
+---@param name string Name of function
+---@param params table<string, any> Array of {param, value} pairs
+---@return pandoc.Div 
+function quarto.format.typst.function_call(name, params) end
+
+--[[
+Create a node that represents typst content (`[Hello, world]`). Use
+this to ensure your output isn't interpreted as typst computations.
+]]
+---@param content any content
+---@return pandoc.Blocks
+function quarto.format.typst.as_typst_content(content) end