How do I create small reusable HTML chunks with variables?

[tim-at-topos]

Description

I am writing a website in Quarto, and I really like being able to keep the contents as .qmd files because these are nice and simple to read and edit — I can give users access to these to make content edits without them having to worry about HTML elements.

However, there are a few HTML snippets that repeat often. For example, whenever I have a button linking to a PDF, I write this in HTML as

<div class="center">
  <a href="$LINK" class="btn btn-outline-secondary">
    <i class="bi bi-filetype-pdf"></i>
    $LINK_TEXT
  </a>
</div>

I would like to be able to turn this into a partial/template (or whatever the correct terminology is here) so that I can simply write something like include(pdf_link, $LINK, $LINK_TEXT) in my .qmd files, and make changes to the pdf_link snippet to change all such buttons globally.

I'm sure this is supported somehow, and is maybe even a Pandoc feature instead of a Quarto one, but I can't find any links to this in the docs (I've tried searching for "partial", "template", and "EJS" but these all seem to just concern writing templates for entires pages instead of snippets, and "snippets" just gives me information about rendering syntax-highlighted code snippets).

[mcanouil]

I've tried searching for "partial", "template", and "EJS" but these all seem to just concern writing templates for entires pages instead of snippets, and "snippets" just gives me information about rendering syntax-highlighted code snippets

Partials are partials not whole templates.

Possible solutions (all documented):

• include shortcode (use raw content code block to include HTML as documented)
• include-* YAML option
• use partials

Note that to add links, there is native feature for that: https://quarto.org/docs/output-formats/html-basics.html#code-links-and-other-links (or https://quarto.org/docs/output-formats/html-multi-format.html if you generate the PDF from the same document)

[mcanouil]

Partials are described in the documentation. The default partials are available to you so what more example you would need?
https://quarto.org/docs/journals/templates.html#html-partials

[Steinthal]

@mcanouil, the OP wants to avoid other users have to deal with HTML. Since links can be inserted at arbitrary places in a document , I'm not sure if YAML or partials are the best solution. It sounds to me that this would be a task for a lua filter.

[mcanouil]

Include shortcode is the simplest way to add the content as I answered.

Of course, you can make your own shortcode or Lua filter but that's more advanced.

• https://quarto.org/docs/extensions/shortcodes.html

[tim-at-topos]

does the {{< include >}} shortcode take arguments? I can't see this in the docs, and in the example I gave I'd want to write something like {{< include _button.qmd $LINK $LINK_TEXT >}}, in which case it sounds like I would have to write a custom shortcode?

[mcanouil]

You can't see this in the documentation because there aren't arguments beside the input file.

[cderv]

If you could consider using computation engine for this, you can create a function in the chosen language to fill your HTML snippet template with desired content, and output for the cells or inline evaluation as raw content in the document.

It would require R, Jupyter or Julia for your rendering, but it would definitely make this easy as the computation happens before any rendering to output.

Example with R using glue for filling the snippet template

---
title: "Quarto Playground"
format: html
---

```{r}
#| include: false
pdf_link <- function(link_text, inline = TRUE) {
  html_snippet <- glue::glue('
  <div class="center">
  <a href="$LINK" class="btn btn-outline-secondary">
    <i class="bi bi-filetype-pdf"></i>
    { link_text }
  </a>
  </div>
  '
  ) |> knitr::raw_html()
  if (inline) {
    return(I(html_snippet))
  } else {
    return(knitr::asis_output(html_snippet))
  }
}
```

Click on the pdf: `{r} pdf_link("Download PDF")`

If you don't want engine, you may also probably leverage Pandoc Lua filter and the fact that Pandoc templating is available in Pandoc's Lua API: https://pandoc.org/lua-filters.html#module-pandoc.template

So you have a template and fill it before inserting in the AST, while hiding this in a shortcode

just an idea I need to experiment with though 😅

[gadenbuie]

@tim-at-topos I made a shortcode extension that works like this called partials and it's specifically designed to let you do something like this:

{{< partial _button.qmd link="https://example.com" text="Example button" >}}

[mcanouil]

I forgot about that extension even-though it's on my listing of extensions: https://m.canouil.dev/quarto-extensions/

[tim-at-topos]

this is perfect, thank you @gadenbuie ! my only question is if there's a way to give absolute paths? e.g. if my partials all live in /_partials/ but I'm editing /blog/post-1/index.qmd then I need to pass ../../_partials/_snippet.qmd as a file path instead of just /_partials/_snippet.qmd

[gadenbuie]

I don't think there is but that'd be a great feature request. Would you mind opening an issue? https://github.com/gadenbuie/quarto-partials

[tim-at-topos]

I will do, and thanks again for this solution, it's fantastic!

[coatless]

This feels like a key native feature to Quarto that is missing. Maybe consider moving toward incorporating it in Quarto v1.7?