Why are there two folders for typst templates?

[cskeeters]

Description

It looks like typst templates are loaded from either:

1. src/resources/formats/typst/pandoc/
2. src/resources/formats/typst/pandoc/quarto/

based on this line:

quarto-cli/src/format/typst/format-typst.ts

Line 88 in 6b363d9

const templateDir = formatResourcePath("typst", join("pandoc", "quarto"));

However, the template used is template.typ (note not a .typst) which only exists in the quarto folder. That file references definitions.typ (again not .typst) and other .typ files. It seems the pandoc files (that may be imported from the pandoc project here https://github.com/jgm/pandoc/blob/main/data/templates/ are not being used.

Furthermore, it seems with pandoc version 3.1.10, they changed to use #quote (a typst buildin) instead of a #blockquote template.

jgm/pandoc@aa95770
https://typst.app/docs/reference/model/quote/

pandoc/definitions.typst was updated to remove the #blockquote template, but it has no effect since pandoc/quarto/definitions.typ was not updated and seems to be used instead.

9ec3879#diff-53e0614088564599b67ca6aa86818022213e6b282307ef1e299269b72679f4cdL2

https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/formats/typst/pandoc/quarto/definitions.typ

What's the rational behind the complexity of two folders?

Part 2

When I use this to create a new extension, it creates an _extensions.yml file with only two of the partials listed.

quarto create extension format

It took me a while to figure out which templates are being used and how to get them copied into the right folder and referenced to get started with a fully custom template. Is there an option to the create extension command that copies all of the files into the folder? If not, it would be nice to have an example in the documentation.

[gordonwoodhull]

I think you've mostly answered your own question, but just to confirm.

1. The rationale is that the templates in formats/typst/pandoc are the original templates from the version of Pandoc we currently bundle (which may be behind the latest release of Pandoc). We copy them here for reference, in order to have something to diff against when we update Pandoc. They are not used directly by Quarto.

   The templates informats/typst/pandoc/quarto are the ones actually used.

   We're right in the middle of a Pandoc update this week, so you may have discovered an update (#blockquote) we still need to make. (I think it will have no effect since this is effectively dead code.)

2. There is yet another copy of these templates in src/resources/create/extensions/format-typst/_extensions/qstart-filesafename-qend. These are the ones that are copied when you run quarto create extension format and are the same except for a descriptive comment.

   Having a command like quarto create extension format --complete is a great idea!

[cskeeters]

Thanks for answering this question. I think this is good documentation for anyone wanting to understand how quarto works.

[gordonwoodhull]

Nod, we are starting to develop more "advanced" documentation for folks building extensions and templates—perhaps this info belongs there.

Up until recently, most of our documentation has been oriented toward users, and I think this is a bit more technical than most users could handle.