Skip to main content

Quarto 1 EJS Listing Template Extension

listing
A listing template: ends in .ejs or .ejs.md — the Quarto 1 EJS convention. Quarto 2 does not run EJS; custom listing templates are doctemplates.

Q-12-9 — Quarto 1 EJS Listing Template Extension

A listing template: ends in .ejs or .ejs.md — the Quarto 1 EJS convention. Quarto 2 does not run EJS; custom listing templates are doctemplates.

What this means

Quarto 1 custom listing templates were EJS — embedded JavaScript (<% for (const item of items) { %>, <%= item.title %>) — under either a .ejs or a .ejs.md extension. Quarto 2 deliberately does not embed a JavaScript runtime: custom listing templates are doctemplates, the $variable$ / $if(…)$ / $for(…)$ syntax Pandoc templates use, so a template can never execute code.

The extension alone is only a naming convention, so this warning fires at configuration time as an early hint. If the file really is EJS, the render-time check Q-12-24 also fires and the listing is skipped rather than pasted into the page.

Why this happens

The listing configuration was carried over from a Quarto 1 project (or copied from a Quarto 1 example) together with its EJS template.

How to fix

Port the template to doctemplate syntax and give it a neutral extension such as .template:

listing:
  type: custom
  template: welcome-card.template   # was welcome-card.ejs

<%= item.title %> becomes $it.title$ inside $for(items)$ … $endfor$; <% if (item.image) { %> becomes $if(it.image)$. Q-12-24 has a fuller mapping table, and the Listings guide lists the values a template can read.

That syntax translation is the mechanical half of the port. The half that fails silently is link and image markup. A doctemplate’s output is markdown, and Quarto resolves paths only after parsing it — so a link written as raw HTML keeps its .qmd href, and an image written as raw HTML is never copied into the site at all. Neither failure produces a warning. Listing templates covers both, and is worth reading before you port rather than after.

If you only renamed the file without porting its contents, you will see Q-12-24 next.