Is there a way to include/embed something on every page?

[venpopov]

Description

I have a quarto website for a research project. I have a bunch of notebooks which I want to move to a section "Archive", and put a callout note on the top of each notebook with a notice that these notebooks are not up-to-date. I can make a separate file with the callout note like this (e.g. _deprecated.qmd):

::: {.callout-note}
Some warning about deprecated reports
:::

and then include it at the begining of each notebook:

--- 
title: "Some notebook"
format: html
---

{{< include _deprecated.qmd >}}

This works, but is there a way to include this in every qmd file in a folder automaticallly via the _metadata.yml file or something like that? I haven't been able to find relevant info on the webpage or github, but I could have missed it

[cscheid]

One way to do it is to define a custom format with a filter that injects the content, and then use that custom format.

Alternatively, you should be able to add a filter to every document in a directory by using directory metadata: https://quarto.org/docs/projects/quarto-projects.html#directory-metadata

[venpopov]

Cool, thanks for the pointers! I haven't worked with filters before but this might be a good test case to learn about them. Though I'll probably leave it for a future project as it seems a lot more work relative to just inserting the shortcode in 10 notebooks manually (would be a different story if I need this for multiple projects and/or a lot more nootebooks.

[mcanouil]

include-before-body in _quarto.yml might work.

[venpopov]

Almost. It includes it in every file, but it adds the raw contents of the file - it does not render the quarto shortcode for a callout.

<main class="content" id="quarto-document-content">
::: {.callout-note}
Some callout
:::

<header id="title-block-header" class="quarto-title-block default"><nav class="quarto-page-breadcrumbs quarto-title-breadcrumbs d-none d-lg-block" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item">Docs</li><li class="breadcrumb-item"><a href="../../docs/archive/file1.html">Archive</a></li><li class="breadcrumb-item"><a href="../../docs/archive/file1.html">First file</a></li></ol></nav>

But I could make it work then by including the html that a callout block would generate. E.g., I make a file _note.html:

<div class="callout callout-style-default callout-note callout-titled">
  <div class="callout-header d-flex align-content-center">
    <div class="callout-icon-container">
      <i class="callout-icon"></i>
    </div>
    <div class="callout-title-container flex-fill">
      Note
    </div>
  </div>
  <div class="callout-body-container callout-body">
    <p>Some callout</p>
  </div>
</div>

and then I have a _metadata.yml file in the archive folder I want to add this note to:

format:
  html:
    include-before-body: ../_note.html

This works nicely:

ideally would be nice to be able to use include-before-body or something similar with .qmd files which get rendered

[cscheid]

ideally would be nice to be able to use include-before-body or something similar with .qmd files which get rendered

That's not something we'll be able to do, because include-before-body is not meant to be used for things in the document body. It's before the body, and a number of features are not supported before the body itself.

Note how, for example, the callout you're getting is happening before the title and breadcrumbs. This is not possible to do in all formats, so we can't just offer the feature.

[venpopov]

I thought that might be the case. Perhaps include-first-in-body, include-last-in-body or similar options could be offered? Not sure if there would be widespread need for this, but for me it is definitely useful.

The usecase that this would be most relevant is for versioned documentation. Imagine a software product that uses quarto for its documentation, and it creates a version of the documentation for each release. As a developer, you might want to include a note in previous version's documents that this is an old version. You might have hundreds of files. Then it would be easy to do by just including a _metadata.yml file in the folders for previous versions.

A real world case of this scenarior is the Stan documentation.

• The current documentation is here: https://mc-stan.org/docs/stan-users-guide/regression.html
• A previous version is here: https://mc-stan.org/docs/2_34/stan-users-guide/regression.html

In the case of Stan, they have a script that craws through the pages of old versions and adds the header "This is an old version, view current version." In this case this is a simle text so they could do it with just the html in include-before-body. But if you want to make it more visible and use quarto or markdown formatting, you would have to write the html yourself, like in my example above. Not the end of the world, but could be streamlined.

[mcanouil]

If you want to include other elements, I suggest you take a look at the partials and templates.

Edit: the link to the documentation https://quarto.org/docs/journals/templates.html#template-partials

[venpopov]

Thanks, I will

[venpopov]

An example of the above solution:

repo: https://github.com/venpopov/quarto_include_before_body
website: https://venpopov.github.io/quarto_include_before_body/archive/file1.html