How do I include images and use relative paths in a Typst Quarto extension?

[mattwarkentin]

Description

Hi,

I have been playing around with developing a Quarto extension that provides a Typst template to format PDF reports (https://github.com/oncology-outcomes/report)

Within the _extensions/reports directory, I have a folder named assets/ thats contains a custom font and some images. I then refer to these images in the typst-template.typ using relative paths which are relative to the root directory where the template.qmd file lives (e.g., "_extensions/report/assets/images/calgary.jpg").

When I try to render the template.qmd within this template repository it works fine. However, when I try to use this template on a new project by running:

quarto use template oncology-outcomes/report

The directory structure for the extension changes from _extensions/report to _extensions/oncology-outcomes/report and this breaks the relative paths to the images. What am I doing wrong here? How should I ship assets with the extension but still refer to the assets with relative paths that don't break?

[mcanouil]

You can't.
Or you would need to use:

• format-resources which will copy the assets next to the document using them (useful for LaTeX but not great for other formats.
• use the LUA tools to compute paths and use them in the template: https://quarto.org/docs/extensions/lua-api.html
• use the full (relative) install path: _extensions/oncology-outcomes/report

[mattwarkentin]

Thanks for the quick response, @mcanouil,

1. I thought about this solution and it would work fine I was just hoping there was a good way to ship but "hide" the assets from the user since they should never need to change them.
2. I will have to look into this option.
3. This does seem like the easiest solution, but it does break the development loop of: make a change to an extension file > render template.qmd > ensure successful render/observe any changes.

[mcanouil]

Maybe resource-path to specify both locations, then you should not even need to write the paths above assets.
I have not tried that.

[mattwarkentin]

Hmm, I did try going down that road but I haven't got it to work yet (if it even can).

[cderv]

To my understanding, what we have done is the following

• path you define in _extension.yml will be resolved with knowledge of the extension installed path. So if you set a relative path as metadata, then you can use this metadata in the template, and it should be the resolved path.

  Example in your _extension.yml

   contributes:
     formats:
       typst:
         (...)
         images:
           calgary-background: "assets/images/calgary.jpg"
  

  Then it typst-template.typ

   //  Calgary image for background
   #let calgary_background={
     image("$images.calgary-background$", width: 100%, fit: "cover")
   }
  

  This way, metadata will get the correct resolved path.

• If the resource needs to be available for rendering from the input directory, then using format-ressources will make a copy. In that case the .typ template can use the relative path directly.

This is what we tried to explain at https://quarto.org/docs/extensions/formats.html#format-resources

Using a path relative to the _extension source is not safe, as it will not be the same path when installed. And the other way makes it hard to develop.

Hope it helps understand our current logic.

[mattwarkentin]

So, basically to make this approach "work" we need to force the path to be treated as raw inline to avoid the escaping of characters, but by doing so we don't allow the path to be resolved when installing the extension. Am I understanding that correctly?

[cderv]

For now, we could also provide a typst helper for extension resources

#let normalize_resource_path(path) = {
  if path.starts-with("\_extensions") {
    path = path.replace("\_extensions", "_extensions")
  }
  return path
}

and then doing this in template would probably solve the issue

#let normalize_resource_path(path) = {
  if path.starts-with("\_extensions") {
    path = path.replace("\_extensions", "_extensions")
  }
  return path
}

//  Calgary image for background
#let calgary_background={
  image(normalize_resource_path("$images.backpage$"), width: 100%, fit: "cover")
}

@mattwarkentin you can try adding that in your template

[cscheid]

@cderv I would almost consider enabling that by default: it would break documents for people who have folders that start with an actual backslash, but, come on :)

[cderv]

So, basically to make this approach "work" we need to force the path to be treated as raw inline to avoid the escaping of characters, but by doing so we don't allow the path to be resolved when installing the extension. Am I understanding that correctly?

What happens is:

• In pandoc, YAML metadata are considered Mardown to be parsed. And Pandoc Typst writer will escape the _ to \_

   ❯ pandoc -f markdown -t typst 
   _extensions
   ^Z
   \_extensions
  

• By using raw inline, this would avoid in this markdown to typst conversion. But using raw inline in YAML field has some consequence.

Now that I remember how pandoc's work in detail, to avoid the Markdown reader applying to metadata, when a variable is needed in a temple, --variable needs to be used instead of --metadata. So this is also working as Quarto leverages Pandoc's default file logic

contributes:
  formats:
    typst:
     (...)
      variables:
        images:
          backpage: assets/images/calgary.jpg

And then keep

//  Calgary image for background
#let calgary_background={
  image("$images.backpage$", width: 100%, fit: "cover")
}

This will also avoid the _extensions to \_extensions problem. Can you try that also @mattwarkentin ? It works when I try on your repo.

[mattwarkentin]

Thanks @cderv, that new approach using variables works great. And thanks to both of you for digging into this. No issues with escaping things.

[mcanouil]

We definitely need a better way to use an extension-provided resource inside the .qmd file. Currently, my "trick" would extent through the {{< meta >}} shortcode where possible to use shortcode.

This trick can't work for instance with include shortcode, etc. So quite limited

[cderv]

That is usually the thing with tricks, they are not perfect, and they don't work in all context, in 100% of situations.

Which is why I said "We definitely need a better way to use an extension-provided resource inside the .qmd file."

[grantmcdermott]

+1 on this issue.

I'm developing a Typst-based extension with custom fonts (licensed for our internal company use) and ran into the same problem with asset paths. Specifically, everything works fine in 'local' development mode. But testing in a different directory after adding my extension template with quarto add <path/to/mytemplate> leads to font failures due to relative path mismatch.

I've tried using format-resources to copy font files and font-paths to specify their location. This works well for command-line rendering via quarto render <some.qmd> --to <mytemplate>.

However, the equivalent interactive preview (Ctrl+Shift+K in VS Code) still fails with "unknown font family" warnings for my Typst documents, even though the fonts are correctly installed in _extensions/<name>/assets/fonts/ and specified via font-paths in _extension.yml.

Honestly, I have no idea why command-line rendering would work, but interactive preview doesn't. If anyone has suggestions for making font paths work consistently across both rendering modes, that would be much appreciated!

---

P.S. My extensions structure looks as follows:

_extensions/mytemplate/
├── _extension.yml
├── typst-show.typ
├── typst-template.typ
└── assets/
    └── fonts/
        └── CustomFont/
            ├── CustomFont-Bold.ttf
            ├── CustomFont-BoldItalic.ttf
            ├── CustomFont-Light.ttf
            ├── CustomFont-LightItalic.ttf
            ├── CustomFont-Regular.ttf
            ├── CustomFont-RegularItalic.ttf
            ├── CustomFont-Thin.ttf
            └── CustomFont-ThinItalic.ttf

and my _extension.yml reads as follows:

title: MyTemplate
author: Your Name
version: 0.1.0
quarto-required: ">=1.7.29"
format-resources:
  - assets/fonts/CustomFont/*.ttf
contributes:
  formats:
    typst:
      template-partials:
        - typst-template.typ
        - typst-show.typ
      font-paths:
        - assets/fonts/CustomFont