How can I use a pre-render approach with a Lua document filter?

[coatless]

Description

I'm thinking about using the pre-render of Quarto to modify a document to create a tabset panel that includes how the code cell was rendered. My goal for doing this is to avoid copying and pasting cell contents to show how the cell was made. I suppose it's an extended/alternative cell-escape sequence that retains the computational order.

For instance, take a Quarto document like:

Original

---
title: "My Code Cell Demo"
format: html
---

```{python}
#| show-cell: true
print("Hello, world!")
```

With Pre-render script:

---
title: "My Code Cell Demo"
format: html
---

:::{.panel-tabset}

#### Rendered

```{python}
#| show-cell: true
print("Hello, world!")
```

#### Source

```{{python}}
#| show-cell: true
print("Hello, world!")
```

:::

I'd like to know if there is a document-facing Lua example that receives the AST for the document. I see there is a note on using the embedded Deno that I would like to avoid using.

[mcanouil]

Pre-render happens before the document is translated into the AST I believe.

This being said, pre-render supports several languages in which you can parse and edit text.

PS: be aware that Pandoc has parsing rules requesting headings and code blocks to be surrounded by empty lines.

[coatless]

@cscheid

1. How can code cells be inserted into the document before evaluation happens?
   • Evaluation refers to the cells being run in the order with which the cells can be found in the document.
2. If code cells need to be inserted into the document at a later time, is there a way to re-trigger the render? (Similar to the quarto.ConditionalBlock API.)

[cscheid]

There isn't a great mechanism to do that at the moment, because all Lua filters run after the engine executes.

[coatless]

If I switch over to Deno/Typescript, same issue?

[cscheid]

With that said, here's a Lua filter that does the specific thing you want (to rearrange a cell output into tabset panels).

It turns out that Tabsets can be constructed directly in Lua code with quarto.Tabset.

There's a small Quarto bug that needs fixing, but the filter below includes a workaround. Hopefully the filter is self-explanatory.

---
format: html
keep-md: true
filters:
  - topanel.lua
---


::: {.to-panel}

```{r}
#| echo: true

print("Hello, world")
```

:::

topanel.lua

function Div(div)
  if not div.classes:includes("to-panel") then 
    return
  end
  local code_block = nil
  local cell_output = nil
  quarto._quarto.ast.walk(div.content, {
    CodeBlock = function(code)
      if code.classes:includes("cell-code") then
        code_block = code
      end
    end,
    Div = function(div)
      if div.classes:includes("cell-output") then
        cell_output = div
      end
    end
  })

  local rendered = quarto.Tab({ title = "Rendered", content = cell_output })
  local source = quarto.Tab({ title = "Source", code_block })
  local tabs = pandoc.List({ rendered, source })

  return quarto.Tabset({
    level = 3,
    tabs = tabs,
    attr = pandoc.Attr("", {"panel-tabset"}) -- this shouldn't be necessary but it's the bug I mentioned.
  })
end

[cscheid]

If I switch over to Deno/Typescript, same issue?

Yes. There really isn't an extension point before Lua filters. With that said, your specific problem has a more specific solution, see above.

[coatless]

@cscheid thank you so much! If you ever are in the bay, let me know I owe you a coffee at the very least!

One last question (sorry!), are the quarto.Tab/quarto._quarto.ast.walk documented somewhere?

[cscheid]

(Paraphrasing)

is quarto.Tab documented somewhere?

This should be, it's an oversight. We do document quarto.Tabset in the Lua typing intelligence we provide, but both quarto.Tabset and quarto.Tab should be documented in general.

is quarto._quarto.ast.walk documented somewhere?

This isn't, and I shouldn't have used it whoops :) You don't need to use that in this case, div:walk ({...}) will work. The difference in our ast.walk method is that finds and processes custom AST nodes (I'm just used to it from developing internal code). We haven't documented its pitfalls just yet, but we also should.