Quarto Guide

Complete reference for using Verified Calculations in your Quarto documents.

Overview

Verified Calculations provides three main components for Quarto:

1. eq - Render canonical formulas from the formula library
2. calc-request - Define inputs for evaluation
3. calc - Insert computed results into your text

The workflow is: define formulas, request calculations, insert results. The calculation service handles the maths.

The eq shortcode

Use eq to render a formula from the library. The formula is displayed as LaTeX maths.

{{< eq id="formula:velocity-time" >}}

This renders the velocity-time equation: v = u + at

Parameters

Browse the formula library to find formula IDs.

Calculation requests

Use a .calc-request div to define inputs for evaluation. This tells the service what to compute.

::: {.calc-request}
request_id: "example-01"
formula_id: "formula:velocity-time"
solve_for: "v"
inputs:
  u: { value: 0, unit: "m/s" }
  a: { value: 9.8, unit: "m/s^2" }
  t: { value: 3, unit: "s" }
options:
  sigfigs: 3
  show_steps: true
:::

Fields

Options

The calc shortcode

Use calc to insert computed values from a calculation request.

The final velocity is {{< calc request="example-01" >}}.

{{< calc request="example-01" field="result.value" >}} m/s

{{< calc request="example-01" field="steps" >}}

Parameters

Available fields

Interactive playground

Add an interactive widget for readers to try calculations themselves:

{{< calc-playground >}}

This renders a form where users can select a formula, enter inputs, and see results in real-time.

Build workflow

There are two ways to use Verified Calculations:

Option 1: Pre-render (recommended)

Evaluate all calculations before Quarto renders. Results are cached in site_data/calcs.json.

# In _quarto.yml
project:
  pre-render:
    - physics-calc pre-render --root . --api https://mentormind-calc.fly.dev --out site_data/calcs.json

Option 2: Runtime (for playgrounds)

The playground widget calls the service directly from the browser. No pre-render needed for interactive use.

Tips and patterns

Naming conventions

• Use descriptive request IDs: projectile-height-01 not calc1
• Group related calculations: problem-2a, problem-2b, problem-2c

Showing working

For worked examples, show the steps:

**Working:**

{{< calc request="example-01" field="steps" >}}

Multiple calculations

You can have multiple calc-request blocks in one document. Each needs a unique request_id.

Error handling

If a calculation fails, the output shows [calc missing request-id:field]. Check:

• The formula_id exists in the library
• The solve_for variable is valid for that formula
• All required inputs are provided
• The pre-render step ran successfully