Dynamically adding a version number to the footer

[cliffckerr]

Description

I'm migrating from Sphinx to Quarto for Python documentation for Starsim. In general, loving it so far :)

However, in Sphinx, you could define variables programatically with conf.py, and then these could be used throughout your documentation. I know in Quarto, there's _variables.yml, but this is, well ... YAML, so it's a bit limited.

Specifically, for a "website", I wanted to be able to write page-footer as "Starsim version `{python} starsim.__version__`", and have it render as e.g. "Starsim version 2.3.2".

This didn't work, so I thought maybe I could include a qmd file as the footer, but that doesn't work either -- _quarto.yml doesn't seem to support commands like {{< include footer.qmd >}} (I just get that literal text, instead of the included file).

My workaround is to call a small Python script that dynamically regenerates _variables.yml before every Quarto build, and then I can use "Starsim version {{< var version >}}" in _quarto.yml. But I would much prefer if I could do this as part of the Quarto build process.

Appreciate any help!

[mcanouil]

As the footer of what?

Could you share a small self-contained "working" (reproducible) example to work with, i.e., a complete Quarto document or a Git repository? The goal is to make it as easy as possible for us to recreate your problem so that we can fix it: please help us help you! Thanks.

---

You can share a self-contained "working" (reproducible) Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).
See https://quarto.org/bug-reports.html#small-is-beautiful-aim-for-a-single-document-with-10-lines.

If you have multiple files (and if it is absolutely required to have multiple files), please share as a Git repository.

R	Python
````qmd --- title: "Reproducible Quarto Document" format: html engine: knitr --- This is a reproducible Quarto document. {{< lipsum 1 >}} ```{r} x <- c(1, 2, 3, 4, 5) y <- c(1, 4, 9, 16, 25) plot(x, y) ``` {#fig-placeholder} {{< lipsum 1 >}} The end after @fig-placeholder. ````	````qmd --- title: "Reproducible Quarto Document" format: html engine: jupyter --- This is a reproducible Quarto document. {{< lipsum 1 >}} ```{python} import matplotlib.pyplot as plt x = [1, 2, 3, 4, 5] y = [1, 4, 9, 16, 25] plt.plot(x, y) plt.show() ``` {#fig-placeholder} {{< lipsum 1 >}} The end after @fig-placeholder. ````

Additionally and if not already given, please share the output of quarto check within a code block (i.e., using three backticks ```txt), see https://quarto.org/bug-reports.html#check.

[cliffckerr]

Sorry, I had hoped that was enough information! It's for a "website" (Python documentation, to be specific). Here's the _quarto.yml file:
https://github.com/starsimhub/starsim/blob/rc3.0/docs/_quarto.yml#L24

It's more a general question rather than a specific "bug", but something like this illustrates the issue:

website:
  title: "Starsim"
  page-footer:
    center: "Starsim version `{python} starsim.__version__`" # does not render as qmd
    ...
    center: footer.qmd # renders as "footer.qmd" instead of the *contents* of footer.qmd
    ...
    center: {{< include footer.qmd >}} # ditto
    ...
    center: "Starsim version {{< var version >}}" # this works, and is what I ended up doing, but requires a custom script to re-generate _variables.yml each time, which I'd like to avoid

[mcanouil]

Then use {{< version >}} to get the Quarto version.

You can define your own shortcode if you want to compute something else.

You can also use pre-render script to populate your variables.

[cliffckerr]

I don't want the Quarto version, I want the version of my package :)

I suppose the pre-render script is the closest to what I'm looking for, although I simply have it in the opposite order (i.e. I have a script that sets the version number and then calls Quarto, rather than Quarto calling a script that sets the version number and then does the build).

Would love if you could write shortcodes in Python and R instead of Lua, though. And I'm still not clear why the {{< include >}} shortcode doesn't work in _quarto.yml.

[mcanouil]

@cliffckerr
Accessibility: To improve accessibility, please add alternative text to your screenshots. This helps all users, including those using screen readers, to understand the context of the images. A brief description can make a big difference! See Good Alt Text, Bad Alt Text — Making Your Content Perceivable.

[cliffckerr]

I've updated the image link with alt text. Are you getting the same output as shown above?

[mcanouil]

Yes and thank you. Could you use your "title" text in the "alt" attribute as well?

[cscheid]

Even in block position, it's still rendering as {{< include _footer.qmd >}} instead of © 2025 My Website..

Ok, that makes sense and yes, it is a block! So let me give a full explanation:

As a very short answer, it's a shortcoming of Quarto that the include shortcode doesn't work on markdown values in _quarto.yml the same way that {{< version >}} does.

Notice that I'm not calling it a bug. That's because it's a design shortcoming. The shortcoming comes when when these two following facts interact:

• include needs to make document inclusions available at the time of engine execution, and so include needs to do its thing very
• Markdown content in YAML is almost entirely handled by Pandoc (for example for title fields, etc). However, we do have the concept of a Markdown envelope, which is built by Quarto ahead of Pandoc (such as websites), but that handling happens relatively late in our pipeline. Crucially, that's after engine execution, and hence after include has already been resolved.

One solution is to move Quarto's handling of Markdown-in-YAML ahead of include execution.

This is a relatively large change in Quarto: it affects engine detection. It changes what Markdown is available during the resolution of include shortcodes. If we were to make such a change, engine detection now would see the markdown envelope.

I actually like this; we need to make the Markdown envelope more explicit and document it. But it needs to be done carefully.

• Move "markdown envelope" earlier in Quarto toolchain #13012

[mcanouil]

I actually like this; we need to make the Markdown envelope more explicit and document it. But it needs to be done carefully

I believe this will solve many opened issues where text does not process markdown currently and related issues.

[cliffckerr]

That makes sense -- thank you!

[mcanouil]

I edited Carlos's reply (marked as the answer) to add the issue link I just created to track this enhancement.

• Move "markdown envelope" earlier in Quarto toolchain #13012