substitutions without user preprocessing

[alan-isaac]

Description

reStructuredText supports substitutions to reuse short, inline content. This is a very useful feature for ensuring consistency across documents (including, e.g., book chapters), so it seems firmly in Quarto's bailiwick. Please consider supporting a similar feature. (I imagine a file of substitution definitions and a new simple syntax for inline substitution.)

[mcanouil]

Same comment as for your other feature request.
You can start with a Lua filter to implement such feature and see how interested is the community.

Note that there are similar Quarto extensions already available such as:

• https://github.com/mcanouil/quarto-div-reuse

I'd love to understand the underlying needs here.
Rather than matching another tool feature-by-feature, it might be more helpful to discuss what workflows you're trying to improve, as it's your second feature request about mimicking reStructedText features.

[alan-isaac]

I have experience with reST, so naturally I notice right away when a feature I used a lot in reST is missing in Quarto. Nevertheless, I only ask for features that I believe many people would use.

The case for substitutions will be evident to anyone who writes long reports. Substitutions allow for changes to be made across a long report in a consistent manner. This is a key use of macros in LaTeX and text substitutions in reST. Although div reuse has some related utility, it is not equivalent functionality.

To give just one example, suppose you are writing a report for a project where the project name is in flux. A ready solution is to use a substitution, and then change the definition in a single location as needed. OK, another example: a report needs to refer repeatedly to a resource, but there is debate over which resource. Just use a text substitution everywhere, changing the definition as needed. OK, yet another example. Or suppose a symbol will get repeated use (as with the callout icons). Each use in a report can be a text substitution, and all uses can be changed consistently at a single location. And on and on.

There has been demand for this among pandoc uses, but the response has been to suggest document preprocessing. This I believe is not suitable for Quarto's target users.

Your suggestion that I just build a Lua filter has problems as well. First of all, I am not familiar will Lua. Of course, this can be treated as my problem, and one I should ameliorate. However, this is really core functionality, and I find it very hard to believe Quarto will not eventually build in some kind of substitution support. Asking new Quarto users to each choose their own syntax for what should be (and I imagine will be) a core feature foregoes the kind of developer debate over best syntax and functionality that is crucial for such a feature.

Build it and they will come. :-)

[cscheid]

You can already use the meta shortcode in these scenarios.

[alan-isaac]

Brilliant. The _variables.yml file is exactly what I wanted. Thank you!

[mcanouil]

Meta/var/env shortcodes seem to be what you need here.

Documentation is available at https://quarto.org/docs/authoring/variables.html