DOCSEARCHbyAlgolia
Submit Docs

QuickAdd Documentation

repository·master·Indexed 25 days ago

https://github.com/chhoumann/quickadd

Documentation for QuickAdd, an Obsidian plugin for automating note creation and content capture. It features a system of 'Choices' (Templates, Captures, Macros, and Multis) to build complex workflows. The docs cover installation, the QuickAdd API for macro and inline scripts, and a comprehensive CLI for running choices, listing available options, and creating notes from templates via the Obsidian CLI.

Tokens
86K
Snippets
170
Records
365
Agent score
80%

What's inside QuickAdd

  1. Overview of QuickAdd Format Syntax

    master

    QuickAdd uses placeholders (e.g., {{DATE}}, {{VALUE}}) that are replaced with real values when a choice runs. These placeholders can be used in file name fields, capture formats, folder paths, "Insert after" targets, and inside template files.

    Quick Reference Table

    Ask for input

    PlaceholderWhat it does
    {{VALUE}}Ask for text
    {{VALUE:title}}Ask for text once, reuse the answer anywhere as title
    {{VALUE:Red,Green,Blue}}Pick from a list
    {{VDATE:due,YYYY-MM-DD}}Ask for a date ("tomorrow" works)
    {{FIELD:project}}Suggest values that property already has in your vault
    {{FILE:People}}Pick a note from a folder
    {{MVALUE}}Write a math formula (LaTeX)

    Dates

    PlaceholderWhat you get
    {{DATE}}Today, like 2026-07-08
    {{DATE:MMMM Do}}Today, formatted your way: July 8th
    {{DATE+7}}Seven days from today
    {{DATE:YYYY-MM|startof:week}}The week's starting month, for weekly notes
    {{TIME}}The current time, like 14:05

    The note you ran QuickAdd from

    PlaceholderWhat you get
    {{LINKCURRENT}}A link to it: [[That note]]
    {{LINKSECTION}}A link to the section your cursor is in
    {{FILENAMECURRENT}}Its file name
    {{FOLDERCURRENT}}Its folder
    {{SELECTED}}The text you had selected

    The note being created

    PlaceholderWhat you get
    {{TITLE}}The new note's file name
    {{FOLDER}}The folder the new note lands in

    Other content

    PlaceholderWhat it inserts
    {{CLIPBOARD}}Whatever you copied last
    {{TEMPLATE:Templates/Meeting.md}}The contents of a template file
    {{MACRO:My Macro}}Whatever a macro returns
    {{GLOBAL_VAR:Header}}A snippet you defined in settings
    {{RANDOM:6}}A random ID like x7k2p9
    - {{DATE:HH:mm}} {{VALUE}}

  2. Browse QuickAdd workflow examples

    master

    QuickAdd provides various ready-made workflows categorized by their 'Choice type' (Capture, Template, or Macro). You can use these examples to copy working patterns for specific automation goals.

    Workflow Categories

    • Capture: Used for quickly adding information to existing notes (e.g., Daily Notes, Kanban boards, or Obsidian Canvas cards).
    • Template: Used for creating new notes based on a structure (e.g., Inbox items or Map of Content (MOC) notes).
    • Macro: Used for complex, scripted workflows that often involve external APIs or multi-step logic (e.g., fetching data from Todoist, TMDB, or Readwise).

    Example Selection Guide

    WorkflowChoice typeSetupPrerequisitesWhat it creates
    Capture to Your Daily NoteCaptureBeginnerDaily note pathTimestamped entries, tasks, quotes, callouts, and table rows
    Add a Task to a Kanban BoardCaptureBeginnerObsidian Kanban pluginA task in a board section
    Fetch Tasks from TodoistCapture and MacroIntermediateTodoist API tokenImported Todoist tasks
    Canvas CaptureCaptureIntermediateAn Obsidian Canvas fileText added to a selected or targeted card
    Add an Inbox ItemTemplateBeginnerInbox folder or noteA new inbox note
    Create an MOC Note with a Link DashboardTemplateIntermediateBase template fileA note with an embedded Base dashboard
    Automatic Book Notes from ReadwiseTemplate and MacroAdvancedReadwise export scriptBook notes with highlights
    Book FinderMacroIntermediateBook lookup scriptA populated book note
    Movie and Series ScriptMacroIntermediateTMDB API keyMedia notes with metadata
    Move Notes with a TagMacroIntermediateTagged notesNotes moved into a target folder
    ZettelizerMacroIntermediateHeadings in an existing noteNew notes split from headings
    Toggl ManagerMacroAdvancedToggl integrationPreset time entries

  3. What is a macro and how does it work?

    master

    A macro is a sequence of commands that run one after another to automate complex workflows. It is triggered by a macro choice (an entry in the QuickAdd menu).

    Macros allow you to:

    • Reuse answers to questions across multiple steps using variables.
    • Run custom JavaScript to interact with the Obsidian API or other plugins.
    • Branch workflows using conditionals.
    • Chain existing QuickAdd choices (templates, captures, etc.) using nested choices.

    Key components:

    • Macro choice: The trigger in the QuickAdd menu.
    • Macro: The actual sequence of commands.
    • Commands: Individual steps (e.g., Obsidian commands, scripts, AI prompts).
    • Variables: Data passed from one command to another within a single macro run.

  4. How to cancel or abort a QuickAdd interactive run

    master

    There are two ways to stop an interactive run, depending on whether you want to dismiss a single prompt or terminate the entire process.

    Dismissing a single prompt

    To simulate the user pressing Escape on a specific prompt, send a POST to /reply with the body:

    {"requestId": "...", "cancelled": true}

    This ends the current prompt. If the prompt type is info, the panel closes but the underlying QuickAdd choice continues to run.

    Terminating the entire run

    To deliberately end the entire execution, use the /abort endpoint:

    POST http://127.0.0.1:<port>/abort?session=<id>&token=<token>
    • This rejects all pending prompts and causes the run to unwind.
    • The run will eventually deliver a terminal event (usually a done or an error like "Input cancelled by user").
    • Warning: /abort only interrupts prompts routed to you. If the run is currently performing work between prompts, it may still complete its side effects. Always poll for the terminal event to be sure.

  5. Choose the right scripting feature

    master

    QuickAdd provides different ways to use JavaScript depending on your workflow needs:

    • User script: Best for larger workflows and shared code that requires reusable logic and settings.
    • Inline script: Best for small data transformations that should stay close to the template or capture format using them.
    • Macro choice: Best for coordinating a sequence of several script and choice steps, managing the order, variables, and abort behavior.
    • Script with settings: Best when you want to allow non-coders to configure script values directly from the QuickAdd UI without editing the JavaScript code.

  6. How to structure a user script

    master

    User scripts must export a module with an entry point. There are two primary patterns:

    1. Simple Function Pattern

    Use this for quick, simple scripts that do not require user-configurable settings.

    module.exports = async (params) => {
    // Your code here
};

    2. Object Pattern (with Settings)

    Use this when you want to provide a UI in QuickAdd for users to configure options (like API keys, toggles, or dropdowns).

    module.exports = {
    entry: start,
    settings: {
        name: "Script Name",
        author: "Your Name",
        options: {
            // Define configurable options here
        }
    }
};

async function start(params, settings) {
    // Your code here
}
    module.exports = {
    entry: start,
    settings: {
        name: "Script Name",
        author: "Your Name",
        options: {
            // Define configurable options here
        }
    }
};

async function start(params, settings) {
    // Your code here
}

  8. Handle the `tags` property during migration

    master

    The tags property is treated as a reserved property to ensure compatibility with Obsidian's native tag system.

    When migrating tags:

    1. The key is normalized to lowercase (tags:).
    2. Any # symbols are stripped from the values.

    Example:

    Input:

    Tags:: #project, #work, #important

    Output:

    ---
tags:
  - "project"
  - "work"
  - "important"
---
    ---
tags:
  - "project"
  - "work"
  - "important"
---

  9. Review what a package can do

    master

    Because importing a package can run scripts and macros with full access to your vault and network, QuickAdd requires a review before any files are written.

    Capability Summary

    The What this package can do panel ranks capabilities by impact:

    • Runs custom JavaScript: A user script or script-mode condition running arbitrary code.
    • Runs on startup: A macro set to run automatically on Obsidian launch.
    • Adds commands: Choices that register a command in the palette or hotkeys.
    • Other actions: Overwriting existing choices/files, sending content to an AI provider, or triggering other Obsidian commands.

    File Review and Security

    • View contents: Click this to read a script or template exactly as it will be written.
    • Executable flag: Files run as code are marked Executable. Very long or minified scripts are flagged as not fully reviewable.
    • Markdown code execution: A Markdown note containing a JavaScript code fence is flagged with a can be run as code capability. This is because user-script steps run the first js fence, and inline js quickadd fences run whenever the note is used as a template (including AI Assistant prompt templates).

    Acknowledgement Gate

    If a package runs code, the Import package button is disabled until you have:

    1. Opened View contents for each bundled executable script.
    2. Ticked the acknowledgement for each.

    Caution: If a referenced script is not bundled in the package, QuickAdd will warn you that it will run from whatever file already exists at that path after import.

  10. Verify execution results and vault effects

    master

    When a command returns {"ok":true}, it means the choice ran without aborting, but it does not guarantee the vault was modified. To determine the actual outcome for automation (like idempotency checks), inspect the verified and effect keys in the JSON response.

    KeyDescriptionValues
    verifiedDid QuickAdd confirm the engine's action?true (outcome confirmed), false (could not look)
    effectWhat did the run do to the vault?created, changed, unchanged, unknown

    Important Notes:

    • effect is only present on success (ok:true). A failed/cancelled run returns error and no effect.
    • verified: false means the outcome was not confirmed; it does not mean nothing changed.
    • If you are counting captures or deciding whether to retry, use the effect key.

  11. Shape entries with Capture format

    master

    The Capture format is a mini-template for the text being inserted. If disabled, QuickAdd simply writes {{VALUE}} (the raw input).

    Usage

    • Format Syntax: All format syntax is supported (e.g., {{DATE}}, {{VALUE}}).
    • External Templates: For complex formats, store the template in a note and reference it using {{TEMPLATE:Path/To/Template.md}}. This allows you to edit and version your capture formats as normal notes.
    • Inline Scripts: If your format includes an inline js quickadd block, use this.quickAddApi.inputPrompt(...) to read input and assign to this.variables. Do not put {{VALUE}} inside JavaScript string literals.

    Important Notes

    • Frontmatter: If a referenced template contains a --- frontmatter block and the target note already has one, you will end up with two blocks. Use Apply Template to Note if you need to merge frontmatter.
    - {{DATE:HH:mm}} {{VALUE}}

  12. Manage QuickAdd Choices and Packages

    master

    QuickAdd allows you to build and organize workflows through Choices and share them via Packages.

    • Choices: The main list where you add, reorder, and configure different workflow types. Common types include Template Choices, Capture Choices, Macro Choices, and Multi Choices.
    • Packages: Used to bundle a set of choices into a file for sharing or to import configurations from others. Use the Export package… and Import package… buttons in the settings to manage these.