Using variables from external file in your Quarto project
My use case is: I need to write some technical, long, documentation where I need to provide some information like IP addresses of used servers, some paths to the application, configuration folders, ...
The normal way to do this is to just put information directly in the documentation and to make sure to update every occurrence in case of changes during the lifecycle of the application.
The best way is probably to use an external file where information are stored in a key-value form and, during the rendering process of Quarto, replace short codes by values.
If you don't have yet a Docker image with Quarto, read this article Running Quarto Markdown in Docker.
You can find the official documentation on https://quarto.org/docs/authoring/variables.html.
Variablesโ
Here is how to proceed:
- First, it's mandatory, you should have a file called
_quarto.yml
in the same directory as the file (let's saydocumentation.md
) you will convert using Quarto. Note: that file can be empty (see https://github.com/quarto-dev/quarto-cli/issues/2918 for more information on this). - Then you should create a file called
_variables.yml
with your key-values and, finally, - You need to have your markdown file.
So, _quarto.yml
can stay empty. His presence is just to tell to Quarto the markdown file is part of a project.
Here is an example of what can be a _variables.yml
content:
version: 1.2
email:
info: info@example.com
support: support@example.com
engine:
jupyter: "[Jupyter](https://jupyter.org)"
knitr: "[Knitr](<https://yihui.name/knitr>)"
And here is a markdown example (file documentation.md
):
---
title: Testing of variables short code.
---
{{< meta title >}}
Version {{< var version >}} is a minor upgrade.
Please contact us at {{< var email.info >}}.
Quarto includes {{< var engine.jupyter >}} and
{{< var engine.knitr >}} computation engines.
As you can see, the short code is something like {{< meta xxx >}}
or {{< var xxx >}}
.
meta
is for metadata of the document like his title and var
to retrieve information's from _variables.yml
.
By running quarto preview documentation.md --to html
, you'll get this:
This solution is perfect when you want to isolate the "static" content of your documentation from variables, i.e. anything that is subject to regular change or would be repeated in several places in your document.
Environment variablesโ
You can too retrieve environment variables using {{< env xxx >}}
but, there, you should first load these variables in case of need.
For instance, you can have a .env
file like this:
APPLICATION_NAME=My application name
VERSION_NUMBER=1.2
Then, before calling the Quarto rendering process, you should load the file. Since I'm using Docker, I do this like this:
docker run --rm -it -v .:/input -w /input --env-file .env cavo789/quarto quarto preview documentation.md --to html
Here is the content of documentation.md
:
---
title: Testing of variables and env short codes.
---
:::{.callout-tip}
## Environment variables
{{< env APPLICATION_NAME >}} v.{{< env VERSION_NUMBER >}}
:::
{{< meta title >}}
Version {{< var version >}} is a minor upgrade.
Please contact us at {{< var email.info >}}.
Quarto includes {{< var engine.jupyter >}} and
{{< var engine.knitr >}} computation engines.
I'm thus using --env-file .env
in the docker run
instruction so Docker will load my variables and make them available in the container. Quarto can then access them.
This solution is even better if you have an application such as Laravel, and therefore already have such an .env file. As a result, you reuse the same values for both the application and the documentation.