Typst format extensions: Appendices and full-width floats

[mvuorre]

Description

Hi all, I wanted to share some quick wins for other Typst extension developers, and possibly for the Quarto team for thinking around the current default Typst template/functionality.

My quarto-preprint extension provides a preprint-typst (naming... 😳) output format that aims to support more of Quarto's common YAML front matter variables, and make better use of Typst functionality over and beyond Quarto's standard Typst template. Here's what the front page looks like:

(As you can see I'm not a designer and am very open for feedback.)

Appendices

I found it very easy to implement appendices by using Quarto's standard div syntax (:::{.appendix}) in combination with the typst-function extension. All I did was implement a very simple appendix() function that resets counters etc., and the div syntax nicely translated to an appendix. AFAIK appendices are not that well supported in Typst yet, but using typst-function made including them easy in a Quarto-friendly manner. Here's example output:

An additional bonus was that when citeproc: true, you can have the references section appear before any appendices.

Note that the heading ## Appendix {.appendix} syntax does not appear to translate so a separate div is required, but that works well in HTML as well.

Full-width floats in two-column mode

This was again relatively easy to tackle with the typst-function extension: We can use Quarto's div syntax to target Typst's place() function that 'breaks out' of the two columns to provide full width content. In my extension, all you need is

::: {.place arguments='auto, scope: "parent", float: true'}
Everything here will span the whole page.
:::

and all content (figures, code, text, etc) in that div will span the whole page. I wish I knew how to enable this for Quarto code chunks, but since the div syntax here doesn't affect any other output formats, it's a small price to pay. Here's an example:

Hope someone finds these helpful.

[cscheid]

Thank you for sharing!

I wish I knew how to enable this for Quarto code chunks

If I understand correctly, you would like to be able to write code cells like this, and then have your extension be able to respond to the place metadata:

The following IS A HYPOTHETICAL EXAMPLE AND DOES NOT ACTUALLY WORK. PLEASE DO NOT USE IT!

```{r}
#| place:
#|   where: auto # YAML doesn't support mixed positional-keyword arguments like typst does, so we need a name for the first parameter
#|   scope: parent
#|   float: true
#| label: fig-1
#| fig-cap: Hello, world
plot(1:20)
```

Do I understand that correctly? If so, it is truly a super cool idea that I would love to be able to do. Unfortunately, Quarto doesn't support anything like it (and, sadly, probably will not support it for a long time; it would require very large changes in our architecture).

In the meantime, you could use the output: asis option and write code that emits the div syntax directly. You could borrow some ideas from the quartor package has helpers for writing metadata: https://github.com/quarto-dev/quarto-r/blob/main/R/metadata.R

[mvuorre]

What I had in my mind was something like in RMarkdown's PDF output, where I could specify out.width="\\textwidth", fig.env="figure*" in the chunk options to output a full-width figure. So I guess similar to what you are suggesting. At the moment though I think the div syntax is very nice since it "just works" (with the typst-function extension and a custom Typst function--something to think about for the default Quarto Typst template?), allows for any content (figures, tables, text, etc.) and doesn't interfere with other formats.

Using the quarto-r package how you suggest is nice, but then that doesn't generalize to other languages?

Also thinking if something like the appendix functionality I showed might work for the default Quarto Typst template? It only needs a custom function in the Typst template, and exposing the function (again using typst-function).

Anyway thanks for the response, and look forward to future developments in the Quarto / Typst space.

[cderv]

What I had in my mind was something like in RMarkdown's PDF output, where I could specify out.width="\textwidth", fig.env="figure*" in the chunk options to output a full-width figure

We are missing Raw Typst output support for this. This could be done with some work:

• Rendering R code blocks in Typst  yihui/knitr#2283

At the moment though I think the div syntax is very nice since it "just works" (with the typst-function extension and a custom Typst function--something to think about for the default Quarto Typst template?)

@cscheid didn't we talk about at some point to allow a Markdown syntax to be able to create raw typst function and block? Something built it? I can't find my note on that, unfortunately

[cscheid]

Quarto has built-in syntax for typst blocks, and the typst-function extension is a much more general implementation.

[cderv]

That was it, so we discussed it and implemented it. Thanks for the link!