GeezerVison

Overview

Many more complex projects have additional processing that needs to take place periodically (e.g. data import and preparation) or even before/after each render. Project scripts are a way to incorporate this processing into your workflow.

Periodic Scripts

You can use the quarto run command to run a TypeScript, R, Python, or Lua script. For example:

Terminal

quarto run import.py

Available script interpreters for quarto run include:

Using TypeScript or Lua enables you to create scripts with no additional installation requirements. On the other hand, if your project is already using Python or R then scripts in those languages might be more convenient.

If you are using TypeScript, please be sure to consult the section below on Deno Scripts for additional details on the Deno standard library and importing external scripts.

Pre and Post Render

You can arrange for one or more scripts to execute before and/or after each render using the pre-render and post-render project options. For example:

project:
  type: website
  pre-render: prepare.py
  post-render: 
    - compress.ts
    - fix-links.py

Note that pre-render and post-render also support arbitrary shell commands. So you could for example use make to do data preparation this way:

project:
  type: website
  pre-render: make prepare

Pre and post render scripts are run with the main project directory.

The following environment variables are passed to pre and post-render scripts (note that all paths are relative to the main project directory):

Scripts can use QUARTO_PROJECT_SCRIPT_PROGRESS and QUARTO_PROJECT_SCRIPT_QUIET to adapt their output, for example by suppressing progress indicators when running in quiet mode or when progress display is not available.

The project metadata and render list will be re-computed after any pre-render scripts have executed, allowing them to modify this project data. For example, a pre-render script might generate additional qmd files or ipynb files that should be rendered.

Note that pre-render scripts cannot modify the project directory, the output directory, or the project type. If a pre-render script modifies any of these values, an error will be returned and the render will fail.

If you have a pre-render step that is expensive, you may want only run it when the entire project is being rendered. Here’s how you would do this in the various supported script languages:

if (!Deno.env.get("QUARTO_PROJECT_RENDER_ALL")) {
  Deno.exit();
}

import os
if not os.getenv("QUARTO_PROJECT_RENDER_ALL"):
  exit()

if (!nzchar(Sys.getenv("QUARTO_PROJECT_RENDER_ALL"))) {
  quit()
}

if not os.getenv("QUARTO_PROJECT_RENDER_ALL") then
  os.exit();
end

Deno Scripts

If you want to create project scripts with TypeScript, quarto run enables you to use the Deno TypeScript interpreter bundled with Quarto. This interpreter also includes much of Deno’s standard library. For example, to use the Deno YAML parser you would do this:

import { parse } from "stdlib/yaml"; // Quarto 1.6 syntax
import { parse } from "https://deno.land/std/yaml/mod.ts"; // Quarto 1.5 and earlier syntax

const config = parse(Deno.readTextFileSync("_quarto.yml"));

import { format } from "https://deno.land/[email protected]/datetime/mod.ts";
import { format } from "jsr:@std/datetime@^0.224.0"

import { format } from "stdlib/datetime";

const multiImport = async (...sources: string[]) => {
    for (const source of sources) {
        try {
            return await import(source);
        } catch (e) {}
    }
}
const { readLines } = await multiImport(
  "stdlib/io", // Quarto 1.6 syntax
  "https://deno.land/std/io/mod.ts", // Quarto 1.5 syntax
);