Quarto filter extension that lets you automatically search and replace strings in quarto document when rendering, in a similar way as simple LaTeX text macros.

Define pairs of search string and replacement in the document yaml, and let quarto do the work. The filter searches document text, including link targets. Replacements may include markdown text modifiers (emphasis) and math inline formulae.

News:

• Format dependent replacements are possible now for all formats that are detectable by quarto extensions, notably pdf and html, see the quarto documentation

• For long lists of replacements, check out extension mergemeta, which allows you to merge in data stored under a different key (not search-replace) in another yaml file, see under Section Tip

Installing

quarto add ute/search-replace

This will install the extension under the _extensions subdirectory. If you're using version control, you will want to check in this directory.

Using

Include the filter in the document's yaml, and add a key search-replace. Under this key, define your search-replace pairs as subkeys in the form search : replace. It is a good idea to start the search key with a special character, such as "+" or ".", although it is not required.

Upon rendering, every string or sub-string that matches a search key will be replaced in the main text, and in link targets. Search keys should not be contained in each other - this would give ambiguous results.

There are some reserved keys (currently only one, but more may be added) that start with --:

• --when-format-- is used to specify abbreviations that are only rendered when the document format matches the following sub-key.

Example:

With the yaml

---
format: html
filters:
  - search-replace
search-replace:
  +quarto: "[Quarto](https://quarto.org)"
  +qurl  : https://quarto.org/docs
  +forml : $\alpha * \beta = \gamma$
  +pyth  : "*Pythagoras' theorem*: $a^2 + b^2 = \\dots$"
  .doo   : "- doodledoo - "
--when-format--:
    html:
      +br    :  "`<br>`{=html}"
      +format: html
      +wewant: "read on screen"
    pdf:
      +br    : "`\\newline`{=latex}"
      +format: pdf
      +wewant: "print on paper"
  +dab   : "**dab**"
  "!dua" : "`duaaah`"
---  

document text

+quarto allows us to write beautiful texts
about +pyth or similar complicated formulas (e.g. +forml),
and to [create our *own* filters](+qurl/extensions/filters.html). +br
Even filters that replace text:+br .doo+dab+dab+dab!dua, +dab!dua!
Since we wanted to +wewant, we chose to render as +form.

gets rendered, if html, as

Quarto allows us to write beautiful texts about Pythagoras' theorem: