Explain the syntax of the format: option in YAML (the '-' has meaning)

[fuhrmanator]

Description

I recently forked an extension to change it, and subsequently renamed some things. However, I was confused as to how the format: option in a document metadata works, and couldn't find an explicit definition. For example:

---
title: "Lexdoc Example"
format:
  lexdoc-html: default
author: J.J. Allaire
date: last-modified
---

## Introduction

*TODO* Create an example file that demonstrates the formatting and features of your format.

The lexdoc-html part of the format specification seems to be using lexdoc to search for a directory lexdoc in _extensions, i.e., _extensions/lexdoc/. Is this correct?

It was confusing to me because that specification isn't in the _extension.yml (or any files for that matter). I was using a text editor to change all instances of the format (e.g., lexdoc) and it couldn't find any. I also couldn't find this in the documentation anywhere at https://quarto.org/docs/extensions/formats.html.

If I'm understanding correctly, it would be problematic to (re)name an extension tech-report (possibly) because the - has meaning to separate the extension name (directory) from the format.

[mcanouil]

The format syntax is <extension-name>-<format> when to use it.

title: Lexdoc
author: J.J. Allaire
version: 1.0.0
quarto-required: ">=1.2.222"
contributes:
  formats:
+    html:
      toc: true
      theme: [yeti, custom.scss]

Where usually, the title is used in lowercase for the directory: _extensions/lexdoc/_extension.yml

Edit:

If I'm understanding correctly, it would be problematic to (re)name an extension tech-report (possibly) because the - has meaning to separate the extension name (directory) from the format.

- does not have "meaning".
The thing that as meaning is that the last word is supposed to be a format known to Quarto, so in your example you need tech-report-html as format in a document and tech-report will be your extension directory/name.

[mcanouil]

To better understand, I suggest trying the quick start guide, especially the command to create a format extension: https://quarto.org/docs/extensions/formats.html#quick-start

[fuhrmanator]

That's a great write-up when you're creating a new extension (I can deduce that it creates a directory with the same name that I supply in the wizard). I'm forking an existing extension (and renaming things), and wanted to understand the syntax of the hook to load the extension.

format: <extension-directory-name>-<format> seems more accurate, since the name one specifies is not stored in any metadata files.

However, I think title: is not really related. Here's another example: https://github.com/quarto-journals/acm/blob/main/_extensions/quarto-journals/acm/_extension.yml. The title: acmart (ACM) format template is a human-readable explanation of the extension. The extension name used in the format: option is from acm in the directory that is created when this is installed.

- does not have "meaning".

Thanks for clarifying. Cheers!

[mcanouil]

However, I think title: is not really related. Here's another example: https://github.com/quarto-journals/acm/blob/main/_extensions/quarto-journals/acm/_extension.yml. The title: acmart (ACM) format template is a human-readable explanation of the extension. The extension name used in the format: option is from acm in the directory that is created when this is installed.

If you change it. By default, title is the name of the directory/extension.
But yes, it's intended to contain a human readable version of the extension name.