I can't figure out metadata extensions

[allefeld]

Description

I'm currently going over all the types of extensions in Quarto, learning how they work so I can see whether they could be useful for me. The one type I can't figure out is metadata.

The template created by quarto create extension metadata has no actual contents, and I could find no worked example in any of the many repositories linked to from the documentation.

Attached is a test I created, mde.zip. It contains a metadata extension called mde in _extensions and files intended to test it in the root of the zip-file. _extension.yml:

title: Mde
author: Carsten Allefeld
version: 1.0.0
quarto-required: ">=1.5.0"
contributes:
  metadata:
    project:
      type: website
      output-dir: _output
      # pre-render: "echo pre-render"
      post-render: "echo post-render"
      preview:
        port: 3333

Result:

• type and preview / port have no effect.

• output-dir, pre-render, and post-render have an effect, though this harmless echo pre-render leads to an error message "Pre-render script resulted in a project change that is now allowed.", so I commented it out.

So it seems that metadata extensions are even more limited than the documentation says ("only merge project-level metadata in the project key"). So limited that it is unclear to me what a metadata extension could possibly be used for?

Without these limitations it would be very useful, e.g. modifying a format in a modular way, i.e. without defining a custom format.

Quarto 1.5.57 on Debian 12.7

[cderv]

So limited that it is unclear to me what a metadata extension could possibly be used for?

If you want to dig in the context, this is where it was added (#9953) towards solving #9948

Here is a use case: You want to provide an extension that offers some pre / post render script. Previously you only could it by offering a custom project extension. Now using a metadata type extension you can do it.

Here is an example: https://github.com/qmd-lab/scheduled-docs

This was a first version to solve some known usecase. There is indeed more to support.

Hope it helps understand.

[allefeld]

I tried to do this in a filter or shortcode extension, but filters are executed by Pandoc after the input has been parsed, which includes expanding macros. The filter comes too late.

[mcanouil]

Have you tried https://quarto.org/docs/prerelease/1.4/lua_changes.html#more-precise-targeting-of-ast-processing-phases?

[allefeld]

I wasn't aware of that, thanks!
I tried it now, but without success.

---

A working Quarto Markdown file which first defines macros and then uses one of them:

\newcommand{\rk}{\operatorname{rk}}
\newcommand{\tr}{\operatorname{tr}}

$$
\rk X
$$

The first "paragraph" containing macro definitions does not appear in the output, but is processed and \rk in the math block is expanded. That works both for HTML with MathJax and for LaTeX.

---

A filter which inserts a first paragraph should therefore do the same:

math-definitions.lua

local math_definitions = [[
\newcommand{\rk}{\operatorname{rk}}
\newcommand{\tr}{\operatorname{tr}}
]]

function Pandoc(doc)
  table.insert(
    doc.blocks,
    1,
    pandoc.Para(math_definitions)
  )
  return doc
end

Quarto Markdown document using the filter:

---
filters:
  - at: pre-ast
    path: math-definitions.lua
---

$$
\rk X
$$

This does not work. The macro definitions appear as a first paragraph, and \rk is not expanded.

I tried other at values, but as far as I can tell, pre-ast is the earliest stage.

---

I think filters are fundamentally not useable for this. Filters modify the AST, but Pandoc expands macros only while creating the AST.

[allefeld]

So it seems I have to use the defaults & input-file hackery within a custom format.

Or I could copy math-definitions.md into each project and use {{< include math-definitions.md >}} – apparently include is not a regular filter-based shortcode but acts before Pandoc is called.

[cderv]

I think filters are fundamentally not useable for this. Filters modify the AST, but Pandoc expands macros only while creating the AST.

Yes I believe this sum it up correctly. Macros expansion is a feature from the Pandoc's Markdown Reader that does use this LaTeX reader feature

apparently include is not a regular filter-based shortcode but acts before Pandoc is called.

Yes, include is not a Lua based shortcode, as it is used to insert Markdown content that needs to be parsed it by Pandoc.