How might I display custom metadata fields in individual pages on my blog?

[danmackinlay]

Description

In my frontmatter for each blog post I have a special key, usefulness, e.g.

title: My cool blogpost
date: 2024-01-01
usefulness: 0

How can I best implement some custom display logic for this field (e.g. maybe I want to display a number of stars equal to the usefulness value, for every blog post?

Templates for individual pages seem not be be obvious; AFAICT the default HTML page for a single post is quarto-cli/src/resources/formats/html/templates/quarto-html.ejs.
Possibly a better way of doing stuff is altering the template-partials which seems to be able to override some bits of the complicated master-template (?), although it seems to use some pandoc templating system distinct from the EJS system used by other parts of the website building toolchain. I think? the template-partials documentation is not terribly clear to me.

There are a few related questions about template-partials:

• How can I add a section to where the meta (title/author/date) information is placed in HTML documents? · quarto-dev/quarto-cli · Discussion #6475
• Extensible / customizable quarto website templates (e.g. permit customize EJS templates) · quarto-dev/quarto-cli · Discussion #6552
• Help with Template Partials · quarto-dev/quarto-cli · Discussion #6756

As such, I suspect that the answer might be simply "try to work it out by trial and error for now" and maybe "please submit a documentation pull request if you succeed". If no-one has a great answer for this, I will work it out by trial and error and answer my own question eventually; but if people have hints that will save time I'd love to hear them

[mcanouil]

Note that EJS templating is for now only available to users for custom listings.
Pandoc templating is available to all, it's the template and partials. You can go through Pandoc documentation to get more on what is Pandoc templating (that's not a Quarto thing).

Take a look at other websites: https://github.com/mcanouil/awesome-quarto#websites-formats
You'll get examples of custom listings, filters, partials, etc.

The discussions you shared are exactly what you want to do.
In the end, it's up to the users, to make their customisation (using partials, EJS template for listings, CSS/SCSS theming, and because they are nearly unlimited, it's not possible to "document all uses cases". It's kind of the purpose of the discussions at of this moment.

[danmackinlay]

Thanks @mcanouil! that is clarifying. For the reference of other readers, the relevant bit of the pandoc documentation is Pandoc Template Syntax.

FWIW although I understand it might not be possible to "document all use cases", I think it is an OK goal to document certain high-leverage bits of the system. I suspect that it could pay dividends to give an explicit introduction to the existence and relationship of the two parallel templating systems (EJS, pandoc) ; as an outsider to the project this has taken a long time for me to deduce. As such I am mentioning these systems right here in the comments in the hope that other readers will save themselves some time.

Towards this goal, some useful things I think I have deduced and/or understood from @mcanouil 's helpful feedback that a future reader might find helpful I will now restate and summarise:

• although the pandoc templates are mentioned under the journal format, they are universal and apply to all formats. the journal format documentation seems to function as the "generic advanced quarto" documentation and is much more general than you might assume
• EJS templates are website format specific.
• although EJS and pandoc formats include partial templates, these partials are not compatible or connected and have a different syntax. I suspect that means that if I wish to customise the metadata in a listing, and in a specific page, I will end up implementing it in two different syntaxes, in two different template systems

Please do correct me if I got anything wrong there.

[mcanouil]

FWIW although I understand it might not be possible to "document all use cases", I think it is an OK goal to document certain high-leverage bits of the system. I suspect that it could pay dividends to give an explicit introduction to the existence and relationship of the two parallel templating systems (EJS, pandoc) ; as an outsider to the project this has taken a long time for me to deduce. As such I am mentioning these systems right here in the comments in the hope that other readers will save themselves some time.

I do agree but this is not without constraint such as time amongst other.
It's also why contribution are very welcome and why I try to aggregate good resources such as videos and blogpost on the Awesome Quarto list (not affiliated to Posit/Quarto): https://github.com/mcanouil/awesome-quarto?tab=readme-ov-file

Please do correct me if I got anything wrong there.

It seems about right.
Pandoc template is the basis of all templates/partials within Pandoc thus also in Quarto since the latter tries to stay close to Pandoc in regards to the templates.
EJS is really another schema of templating designed for the web: https://ejs.co/
So if you intend to build HTML-based complex things, yes EJS + Pandoc templating system might intersect. (note that these two things are two third party features that Quarto is only borrowing)