YAML arguments not being passed to my Typst template partials

[mattwarkentin]

Description

Hi,

I am trying to create my first Typst custom format. However, I am running up against an issue where the YAML arguments in the Quarto document are not being passed to typst-template.typ. I have tried to strip away the unnecessary code from my templates to try to provide a minimal example and hopefully identify the issue.

Even though I have set the toc: false argument, a ToC is still included in the report.

Quarto document (template.qmd)

---
title: This is the title of my report.
format: 
  report-typst:
    toc: false
---

# Introduction

## Second level

### Third level

#### Fourth level

# Methods

# Results

Typst Show (typst-show.typ)

#show: doc => report(
$if(title)$
  title: [$title$],
$endif$
$if(subtitle)$
  subtitle: [$subtitle$],
$endif$
$if(date)$
  date: [$date$],
$endif$
$if(lang)$
  lang: "$lang$",
$endif$
$if(region)$
  region: "$region$",
$endif$
$if(margin)$
  margin: ($for(margin/pairs)$$margin.key$: $margin.value$,$endfor$),
$endif$
$if(papersize)$
  paper: "$papersize$",
$endif$
$if(mainfont)$
  font: ("$mainfont$",),
$endif$
$if(fontsize)$
  fontsize: $fontsize$,
$endif$
$if(toc)$
  toc: $toc$,
$endif$
$if(toc-title)$
  toc_title: [$toc-title$],
$endif$
$if(toc-indent)$
  toc_indent: $toc-indent$,
$endif$
$if(toc-depth)$
  toc_depth: $toc-depth$,
$endif$
$if(lof)$
  lof: $lof$,
$endif$
$if(lof-title)$
  lof_title: [$lof-title$],
$endif$
$if(lot)$
  lot: $lot$,
$endif$
$if(lot-title)$
  lot_title: [$lot-title$],
$endif$
  doc,
)

Typst Template (typst-template.typ)

#let report(
  title: none,
  subtitle: none,
  date: none,
  margin: (x: 1.25in, y: 1.25in),
  paper: "us-letter",
  lang: "en",
  region: "US",
  font: (),
  fontsize: 12pt,
  toc: true,
  toc_title: "Table of contents",
  toc_depth: 3,
  toc_indent: 1.5em,
  lof: true,
  lof_title: "List of figures",
  lot: true,
  lot_title: "List of tables",
  doc,
) = {
  if toc {
    block(above: 0em, below: 2em)[
    #outline(
      title: toc_title,
      depth: toc_depth,
      indent: toc_indent
    );
    ]
    pagebreak(weak: true)
  }

  set page(numbering: "1")

  if lof {
    block(above: 0em, below: 2em)[
    #outline(
      title: lof_title,
      target: figure.where(kind: "quarto-float-fig")
    );
    ]
    pagebreak(weak: true)
  }

  if lot {
    block(above: 0em, below: 2em)[
    #outline(
      title: lot_title,
      target: figure.where(kind: "quarto-float-tbl")
    );
    ]
    pagebreak(weak: true)
  }

  doc
}

Snippet of the rendered Typst document (template.typ from keep-typ: true)

Somewhere along the way it is picking up toc_title and toc_depth but not the actual argument I'm passing, toc.

#show: doc => report(
  title: [This is the title of my report.],
  date: [2024-11-15],
  lang: "en",
  font: ("Narin",),
  fontsize: 12pt,
  toc_title: [Table of contents],
  toc_depth: 3,
  doc,
)

[mattwarkentin]

From the terminal during rendering...so toc is being passed on to pandoc.

pandoc 
  to: typst
  output-file: template.typ
  standalone: true
  default-image-extension: png
  wrap: none
  citeproc: false
  toc: false
  
metadata
  font-paths: _extensions/report/assets/fonts
  mainfont: Narin
  fontsize: 12pt
  lang: en
  subtitle: Oncology Outcomes (O2)
  date: today
  title: This is the title of my great report.
  
[typst]: Compiling template.typ to template.pdf...DONE

Output created: template.pdf

[mattwarkentin]

Sure, here it is: https://github.com/oncology-outcomes/report

[mattwarkentin]

FWIW, when setting the following YAML params:

---
title: This is an example report
format: 
    report-typst:
        foo: bar
        toc: false
---

It seems like toc is passed to pandoc but not metadata available to typst-show.typ.

pandoc 
  to: typst
  output-file: template.typ
  standalone: true
  default-image-extension: png
  wrap: none
  citeproc: false
  toc: false
  
metadata
  font-paths: _extensions/report/assets/fonts
  mainfont: Narin
  fontsize: 12pt
  lang: en
  subtitle: Oncology Outcomes (O2)
  date: today
  title: This is an example report
  foo: bar
  
[typst]: Compiling template.typ to template.pdf...DONE

Output created: template.pdf

[mattwarkentin]

As best as I can tell, it seems like some YAML arguments are being swallowed by Quarto and not passed on. It seems like if the argument is a default Quarto YAML argument (e.g., toc), it doesn't get passed through to Typst. If I use a custom YAML argument like foo or something else, it works fine.

[cderv]

I believe this is quiet specific to how Pandoc's handle metadata as variable for template, and how toc specifically is handled.

Let's start by Pandoc's documentation about variable for template and how they are counted inside if() https://pandoc.org/MANUAL.html#conditionals

The following values count as true:

• any map
• any array containing at least one true value
• any nonempty string
• boolean True

Note that in YAML metadata (and metadata specified on the command line using -M/--metadata), unquoted true and false will be interpreted as Boolean values. But a variable specified on the command line using -V/--variable will always be given a string value. Hence a conditional if(foo) will be triggered if you use -V foo=false, but not if you use -M foo=false.

This means when you use in your template

$if(toc)$ toc: $toc$, $endif$

you expect, toc: false but this won't happen because the if is not triggered.

This is not about the metadata not passing, this is about how it applies. You don't see the effect, because your template default to toc: true in the template https://github.com/oncology-outcomes/report/blob/57bd9044e523a6802a3a2dbf4148a3c8579c61f5/_extensions/report/typst-template.typ#L79-L81

Try setting to toc: false in typst-template.typ and then do

format: 
  report-typst:
    toc: true

You'll see it works.

As you want to reverse the default, you need to specifically handle this in your template. If you define a default, you probably don't need to use $if(toc)$.

• Under _extension.yml add toc: true in your format as you want it by default.
• Then adapt your .typ template to use correctly get handle when toc: false is passed in YAML.
  • I would say don't use $if(toc)$ as this will be always defined in your case
  • Or don't set toc: true in your format typst definition in typst so that no presence in show rule does not mean true.

I hope this makes thinks clearer.

To be clear, this is a specific of Pandoc behavior with metadata used as variable for template, and even more specific to toc.

I am saying this is more specific for toc metadata because in Pandoc, it is not a metadata per-se. Pandoc will see this metadata we pass in the default files, then it will set the writer option flag, that Pandoc use internally to set the toc variable.

More details - though I hope I managed to keep the explanation easy to understand.

Hope it helped

[mattwarkentin]

Thanks for the detailed response, @cderv. Very much appreciated. I think I am following along with what you have described. I think the inner workings of how YAML and metadata are captured and passed around are a little translucent to me, but this definitely helps my mental model and clarifies why toc specifically acts differently than some other arguments.

[cderv]

If you need to leave this thread with one thing for your next template.
Beware of the template logic:

$if(var)$ field: $var$$endif$

if var is false, you won't see field at all, so you can't have field: false in your template.

[mattwarkentin]

Thanks, that's actually a very helpful summary of this discussion.