Scripting Overview

QuickAdd scripts are JavaScript files that run inside Obsidian. They can ask you for input, call Obsidian’s own APIs, read data from other plugins, and hand values back to a Macro. This page helps you pick which kind of script to write, then points you at the detailed guides.

You don’t need to be a programmer to use scripting, but you do need to be comfortable pasting and lightly editing JavaScript.

Which one do I want?

Need	Use	Why
A reusable script with settings	User script	Best for larger workflows and shared code
A small transformation inside a template or capture	Inline script	Keeps tiny logic close to the format using it
Several script and choice steps in sequence	Macro choice	Coordinates order, variables, and abort behavior
A script users can configure from the QuickAdd UI	Script with settings	Lets non-coders change values without editing JavaScript

What a user script looks like

Every user script exports one function. QuickAdd calls it with a params object and waits for it to finish:

module.exports = async (params) => {
  const { app, quickAddApi, variables } = params;
  const title = await quickAddApi.inputPrompt("Title");

  variables.title = title;
  return title;
};

The params object is how your script reaches everything it needs:

• app: the Obsidian app instance
• quickAddApi: QuickAdd’s prompt, utility, AI, and execution helpers
• variables: values shared across macro steps

How a value travels through a macro

When a macro runs several steps, they pass values to each other through the shared variables object:

1. A choice or script asks for a value.
2. QuickAdd stores that value in variables.
3. Later template, capture, and script steps can reuse it.
4. If a prompt is cancelled, QuickAdd aborts the macro unless your script handles the cancellation.

Use named values like {{VALUE:project}} when several macro steps should share one prompt.

A good order to learn this in

1. Macro Choices for how macro steps are assembled.
2. User Scripts for complete scripting patterns.
3. Scripts with Settings for configurable scripts.
4. QuickAdd API Reference for exact method details.

Debugging

Sprinkle console.log through a script while you build it, then read the output in Obsidian’s developer console. Keep each script small enough that you can test one step at a time before wiring it into a longer macro.