Help with custom Typst format

[aaronschiff]

Description

Hi folks, I'm trying to create a custom Typst template to produce pdf documents from Quarto where the layout of each page is like the image below. The title and text in the grey column will be written in the qmd file and the chart will be created in R code. This type of layout is possible with Typst's grid() function but I can't figure out how to connect it to Quarto. Specifically, I can't figure out how to define which part of the qmd file is the grey column and which part is the chart, and how to pass that information from Quarto to the Typst template.

I've seen the "Dept news" template which uses grid() but that was too complicated for me to follow as I'm still relatively new to this. Does anyone have any suggestions to help get me on the right track, or links to similar examples that I can adapt?

Thanks!

[aaronschiff]

I figured out a way to do this based on studying the "Dept news" template for several days 😅. Not sure if it's the best way but it seems to work. I've put the main parts below in case it's useful to someone else.

In the .qmd file for my document, we can use divs to distinguish the left and right panels:

::: {.leftpanel}
# Heading 1

Hello world.

# Heading 2

Hello again.
:::

::: {.rightpanel}
```{r}
#| echo: false
#| message: false
#| warning: false
library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) +
  geom_point() +
  geom_smooth(method = "loess", se = FALSE)
```
:::

I created a Typst format extension for Quarto with the template. In the _extension.yml file we specify a filter (asdv.lua) that will translate the divs from the qmd file into something that Typst can understand:

title: asdv
version: 1.0.0
quarto-required: ">=1.5.0"
contributes:
  formats:
    typst:
      papersize: a4
      flipped: true
      margin:
        x: 1cm
        y: 1cm
      template-partials:
        - typst-template.typ
        - typst-show.typ
      filters:
        - asdv.lua

The filter code detects the leftpanel and rightpanel div classes and converts their contents into Typst code expressions. For example, the resulting Typst output will include #leftpanel[ ... ], where ... is the contents of the .leftpanel div from the qmd file. Typst will interpret this as a call to a function leftpanel, which we will need to define in our template code.

function Div(el)
  if el.classes:includes('leftpanel') then
    local blocks = pandoc.List({
      pandoc.RawBlock('typst', '#leftpanel[')
    })
    blocks:extend(el.content)
    blocks:insert(pandoc.RawBlock('typst', ']\n'))
    return blocks
  elseif el.classes:includes('rightpanel') then
    local blocks = pandoc.List({
      pandoc.RawBlock('typst', '#rightpanel[')
    })
    blocks:extend(el.content)
    blocks:insert(pandoc.RawBlock('typst', ']\n'))
    return blocks
  end
end

For the Typst template, the typst-show.typ file can be left as-is, or unnecessary parts can be deleted (e.g. the abstract in my case).

In typst-template.typ, we need to define the leftpanel and rightpanel functions to capture the content that is passed to them, in a way that can be used in the main article() function that gets called to generate the document output. Typst doesn't support global variables (I think) so we have to use its state functions for this purpose. The way we do this is to create two state variables, and then create the leftpanel and rightpanel functions to update those state variables with the content that is passed to them:

#let leftpanel_state = state("leftpanel_state", ())
#let rightpanel_state = state("rightpanel_state", ())

#let leftpanel(body) = leftpanel_state.update(it => it + (body,))
#let rightpanel(body) = rightpanel_state.update(it => it + (body,))

Now finally we can use the leftpanel_state and rightpanel_state in a call to grid() in the article() function of the template. We do this by some magic involving locate() that I don't really understand, but it works. I used grid.cell() for each part of the grid to format them differently.

Here's the full article() function that I used:

#let article(
  title: none,
  authors: none,
  date: none,
  margin: (x: 10mm, y: 10mm),
  paper: "a4",
  flipped: false,
  lang: "en",
  region: "US",
  font: (),
  fontsize: 11pt,
  doc
) = {
  set page(
    paper: paper,
    flipped: flipped,
    margin: margin,
    numbering: none,
  )
  set par(justify: true)
  set text(lang: lang,
           region: region,
           font: font,
           size: fontsize)
  set heading(numbering: none)

  doc

  grid(
    rows: (10%, 90%),
    columns: (30%, 70%),
    inset: 8pt,
    // Title
    grid.cell(
      text(weight: "bold", size: 1.5em)[#title],
      colspan: 2
    ),
    // Left panel
    grid.cell(
      locate(loc => {
        for element in leftpanel_state.final(loc) {
          element
        }
      }),
      fill: rgb("CCCCCC")
    ),
    // Right panel
    grid.cell(
      locate(loc => {
        set image(width: 100%)
        for element in rightpanel_state.final(loc) {
          element
        }
      }),
      align: center + horizon
    )
  )
}

And here is the resulting pdf output. If anyone has any suggestions of how to improve or simplify this method, I'd love to know.

[cscheid]

This looks great!

[aaronschiff]

I just realised this solution only works for one-page documents. A logical approach to specify pages in the qmd file would be to use nested divs with a page wrapper and divs for the panels inside each page. If I figure out how to make that work I'll add an update.

[serigra]

This is so helpful! Thank you for documenting!