AGENTS.md

quarto-julia-engine

This repo contains the Julia execution engine for Quarto. The engine was originally built directly into quarto-cli but has since been refactored into an extension-style engine, moved into this separate repo, and is pulled into quarto-cli via a git subtree at src/resources/extension-subtrees/julia-engine/.

The engine extension requires a compatible version of quarto (>= 1.9.0). If work involves changes to the engine–quarto interface, you'll also need a corresponding dev build of quarto-cli with matching changes.

Repo structure

• _extensions/julia-engine/ — the actual extension (contains _extension.yml, the bundled julia-engine.js, and Julia resource files like Project.toml, *.jl)

• src/ — TypeScript source for the engine (julia-engine.ts, constants.ts). Changes here must be bundled into _extensions/julia-engine/julia-engine.js to take effect.

• _quarto.yml — makes the repo root a quarto project so rendering picks up the extension from _extensions/

• tests/ — self-contained test suite (see Testing below)

Building

After editing the TypeScript source in src/, rebuild the bundled JS:

quarto call build-ts-extension src/julia-engine.ts

This bundles src/julia-engine.ts into _extensions/julia-engine/julia-engine.js. CI verifies the bundled JS matches the TS source.

Testing

Tests are self-contained Deno tests using jsr: imports — no import map or quarto internals needed. tests/docs/ contains .qmd files and quarto projects that the .test.ts files in tests/smoke/ render and verify. These directories mirror quarto-cli's tests/docs/ and tests/smoke/ structure and are intended to be merged into those directories when quarto-cli runs its own CI (since this extension is a fixed part of quarto-cli via git subtree).

Running tests locally

The test runner uses the deno bundled with quarto (to avoid version mismatches):

# With quarto on PATH:
tests/run-tests.sh

# With explicit quarto path:
QUARTO=/path/to/quarto tests/run-tests.sh

# Run a specific test file:
tests/run-tests.sh smoke/julia-engine/render.test.ts

Quick: render in this repo

Create or edit a .qmd file in the repo root (e.g. in scratch/) with engine: julia and render it:

quarto render scratch/test.qmd

Since this directory is a quarto project with the extension in _extensions/, quarto discovers and uses the engine from here.

CI

CI runs on all three platforms (Linux, macOS, Windows) against a pinned quarto-cli revision (see QUARTO_CLI_REV in .github/workflows/ci.yml). It:

1. Configures quarto from the pinned rev

2. Verifies the bundled JS is up to date with the TS source

3. Runs the full test suite

When bumping QUARTO_CLI_REV, use the full commit hash annotated with the version tag for clarity (e.g. abc123 # v1.9.35).