diff --git a/docs/docs/Advanced/APIOverview.md b/docs/docs/Advanced/APIOverview.md new file mode 100644 index 00000000..88eb8062 --- /dev/null +++ b/docs/docs/Advanced/APIOverview.md @@ -0,0 +1,51 @@ +--- +title: API Overview +--- + +Use the QuickAdd API when a workflow needs scripted input, file operations, +formatting, model calls, or access from another plugin. + +If you only need to create a note or append text, start with +[Template Choices](../Choices/TemplateChoice) or +[Capture Choices](../Choices/CaptureChoice). Add the API when the workflow +needs logic. + +## Where the API is available + +| Context | Access pattern | Use it for | +| --- | --- | --- | +| Macro user script | `params.quickAddApi` | Scripted macro steps | +| Inline script | `this.quickAddApi` | Small transformations inside templates or captures | +| Other plugin | `app.plugins.plugins.quickadd.api` | Calling QuickAdd from plugin code | +| Templater script | `app.plugins.plugins.quickadd.api` | Prompting or running choices from Templater | + +## Common tasks + +| Task | Method family | Reference | +| --- | --- | --- | +| Ask for text, selections, dates, or grouped inputs | User input methods | [QuickAdd API Reference](../QuickAddAPI#user-input-methods) | +| Run another choice from a script | Choice execution | [Choice Execution](../QuickAddAPI#choice-execution) | +| Read selected text or clipboard content | Utility module | [Utility Module](../QuickAddAPI#utility-module) | +| Format dates | Date module | [Date Module](../QuickAddAPI#date-module) | +| Call configured AI providers | AI module | [AI Module](../QuickAddAPI#ai-module) | +| Read field suggestions from the vault | Field suggestions module | [Field Suggestions Module](../QuickAddAPI#field-suggestions-module) | + +## Recommended path + +1. Read the [scripting overview](./ScriptingGuide) if you have not written a + QuickAdd script before. +2. Copy a working pattern from the [examples overview](../Examples/). +3. Use the [QuickAdd API reference](../QuickAddAPI) for exact signatures and + edge-case behavior. + +## Minimal macro script + +```javascript +module.exports = async ({ quickAddApi }) => { + const title = await quickAddApi.inputPrompt("Book title"); + return `# ${title}`; +}; +``` + +The returned value can be used by later macro steps or inserted through format +syntax. diff --git a/docs/docs/Advanced/ScriptingGuide.md b/docs/docs/Advanced/ScriptingGuide.md new file mode 100644 index 00000000..1563659c --- /dev/null +++ b/docs/docs/Advanced/ScriptingGuide.md @@ -0,0 +1,58 @@ +--- +title: Scripting Overview +--- + +QuickAdd scripts are JavaScript files that run inside Obsidian. They can prompt +for input, call Obsidian APIs, read other plugins, and pass values back into a +Macro choice. + +## Which scripting feature should I use? + +| 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 | + +## Basic user script shape + +```javascript +module.exports = async (params) => { + const { app, quickAddApi, variables } = params; + const title = await quickAddApi.inputPrompt("Title"); + + variables.title = title; + return title; +}; +``` + +The `params` object gives scripts access to: + +- `app`: the Obsidian app instance +- `quickAddApi`: QuickAdd's prompt, utility, AI, and execution helpers +- `variables`: values shared across macro steps + +## How values move through a macro + +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. + +## Suggested learning order + +1. [Macro Choices](../Choices/MacroChoice) for how macro steps are assembled. +2. [User Scripts](../UserScripts) for complete scripting patterns. +3. [Scripts with Settings](./scriptsWithSettings) for configurable scripts. +4. [QuickAdd API Reference](../QuickAddAPI) for exact method details. + +## Debugging + +Use `console.log` while developing scripts, then check Obsidian's developer +console. Keep scripts small enough that each step can be tested independently +before adding it to a longer macro. diff --git a/docs/docs/Choices/CaptureChoice.md b/docs/docs/Choices/CaptureChoice.md index 6d8890c0..cde8d89d 100644 --- a/docs/docs/Choices/CaptureChoice.md +++ b/docs/docs/Choices/CaptureChoice.md @@ -103,7 +103,8 @@ When append-link is set to **Enabled (requires active file)** and capture runs from a Canvas card without a focused Markdown editor, the capture still writes and link insertion is skipped. -A dedicated Canvas walkthrough page will return in a future update. +For a step-by-step setup, see +[Capture: Canvas Capture](../Examples/Capture_CanvasCapture). ### Canvas Capture FAQ diff --git a/docs/docs/Examples/Capture_CanvasCapture.md b/docs/docs/Examples/Capture_CanvasCapture.md new file mode 100644 index 00000000..b37ec89e --- /dev/null +++ b/docs/docs/Examples/Capture_CanvasCapture.md @@ -0,0 +1,86 @@ +--- +title: "Capture: Canvas Capture" +--- + +Canvas capture lets a Capture choice write into a selected Canvas card or into a +specific card in a specific `.canvas` file. + +## When to use this + +Use Canvas capture when your workflow starts in a visual board, but you still +want QuickAdd's capture formats, variables, and hotkeys. + +Good fits: + +- Add a timestamped note to a selected brainstorming card. +- Append a task to a project card. +- Send repeated updates to one known Canvas card. + +## Capture to the selected card + +1. Create a Capture choice. +2. Enable **Capture to active file**. +3. Open a Canvas file. +4. Select exactly one supported card. +5. Set **Write position** to **Top of file**, **Bottom of file**, or + **After line...**. +6. Run the Capture choice. + +Supported selected-card targets: + +- Text cards +- File cards that point to Markdown files + +QuickAdd aborts with a notice if no card is selected, multiple cards are +selected, or the selected card is unsupported. + +## Capture to a specific card + +1. Create a Capture choice. +2. Turn off **Capture to active file**. +3. Set **Capture To** to a `.canvas` file. +4. Choose **Target canvas node**. +5. Pick the card you want QuickAdd to write to. +6. Set a supported write position. + +This is the best option for repeatable workflows where every capture should go +to the same Canvas card. + +## Write position support + +Canvas capture supports these write positions: + +- **Top of file** +- **Bottom of file** +- **After line...** + +Canvas capture does not support cursor-based write positions: + +- **At cursor** +- **New line above cursor** +- **New line below cursor** + +If **Capture to active file** is enabled and the write position is still +**At cursor**, QuickAdd aborts instead of writing to the wrong place. + +## Append-link behavior + +When append-link is set to **Enabled (requires active file)** and capture runs +from a Canvas card without a focused Markdown editor, the capture still writes. +QuickAdd skips link insertion because there is no active Markdown file to link +from. + +## Troubleshooting + +| Symptom | Likely cause | Fix | +| --- | --- | --- | +| Capture aborts before writing | No card or multiple cards are selected | Select exactly one supported card | +| Capture aborts with cursor-position wording | The write mode is cursor-based | Use top, bottom, or after-line placement | +| Nothing is written to a file card | The file card points to a non-Markdown file | Use a Markdown file card or a text card | +| The target picker is not shown | Capture target is not a `.canvas` file | Set **Capture To** to the Canvas file path | + +## Related docs + +- [Capture Choices](../Choices/CaptureChoice) +- [Format Syntax](../FormatSyntax) +- [Template: Create an MOC Note with a Link Dashboard](./Template_CreateMOCNoteWithLinkDashboard) diff --git a/docs/docs/Examples/index.md b/docs/docs/Examples/index.md new file mode 100644 index 00000000..176d308f --- /dev/null +++ b/docs/docs/Examples/index.md @@ -0,0 +1,40 @@ +--- +title: Examples +--- + +Use these examples when you want to copy a working pattern instead of starting +from a blank choice. + +| Workflow | Choice type | Setup | Prerequisites | What it creates | +| --- | --- | --- | --- | --- | +| [Add Journal Entry](./Capture_AddJournalEntry) | Capture | Beginner | Daily note or journal file | A timestamped journal entry | +| [Add a Task to a Kanban Board](./Capture_AddTaskToKanbanBoard) | Capture | Beginner | Obsidian Kanban plugin | A task in a board section | +| [Fetch Tasks from Todoist](./Capture_FetchTasksFromTodoist) | Capture and Macro | Intermediate | Todoist API token | Imported Todoist tasks | +| [Canvas Capture](./Capture_CanvasCapture) | Capture | Intermediate | An Obsidian Canvas file | Text added to a selected or targeted card | +| [Add an Inbox Item](./Template_AddAnInboxItem) | Template | Beginner | Inbox folder or note | A new inbox note | +| [Create an MOC Note with a Link Dashboard](./Template_CreateMOCNoteWithLinkDashboard) | Template | Intermediate | Base template file | A note with an embedded Base dashboard | +| [Automatic Book Notes from Readwise](./Template_AutomaticBookNotesFromReadwise) | Template and Macro | Advanced | Readwise export script | Book notes with highlights | +| [Book Finder](./Macro_BookFinder) | Macro | Intermediate | Book lookup script | A populated book note | +| [Movie and Series Script](./Macro_MovieAndSeriesScript) | Macro | Intermediate | TMDB API key | Media notes with metadata | +| [Move Notes with a Tag](./Macro_MoveNotesWithATagToAFolder) | Macro | Intermediate | Tagged notes | Notes moved into a target folder | +| [Zettelizer](./Macro_Zettelizer) | Macro | Intermediate | Headings in an existing note | New notes split from headings | +| [Toggl Manager](./Macro_TogglManager) | Macro | Advanced | Toggl integration | Preset time entries | + +## Pick by goal + +### Capture information faster + +Start with [Add Journal Entry](./Capture_AddJournalEntry) if you want the +simplest capture flow. Move to [Canvas Capture](./Capture_CanvasCapture) when +your target is a Canvas card instead of a Markdown note. + +### Create structured notes + +Start with [Add an Inbox Item](./Template_AddAnInboxItem) for a small template. +Use [Create an MOC Note with a Link Dashboard](./Template_CreateMOCNoteWithLinkDashboard) +when you want a generated note to include a live Base dashboard. + +### Run scripted workflows + +Start with [Book Finder](./Macro_BookFinder) to see the common macro pattern: +prompt for input, call a script, write a note, and open the result. diff --git a/docs/docs/QuickAddAPI.md b/docs/docs/QuickAddAPI.md index f98e0b39..d84d85d8 100644 --- a/docs/docs/QuickAddAPI.md +++ b/docs/docs/QuickAddAPI.md @@ -2,6 +2,13 @@ The QuickAdd API provides a powerful interface for automating tasks in Obsidian through scripts, macros, and inline scripts. The API offers methods for user interaction, file manipulation, AI integration, and more. +:::tip Start with the overview + +If you are choosing which API surface to use, read the +[API Overview](./Advanced/APIOverview) first. This page is the full reference. + +::: + ## Accessing the API The API can be accessed in several ways: diff --git a/docs/docs/UserScripts.md b/docs/docs/UserScripts.md index 2c6eea79..c33b6f26 100644 --- a/docs/docs/UserScripts.md +++ b/docs/docs/UserScripts.md @@ -1,8 +1,15 @@ # User Scripts +:::tip New to scripting? + +Start with the [Scripting Overview](./Advanced/ScriptingGuide) for the +decision path, then use this page as the detailed reference. + +::: + User scripts are JavaScript files that extend QuickAdd's functionality with custom code. They can be used within macros to perform complex operations, integrate with external APIs, and automate sophisticated workflows. -> 📚 **Obsidian API Reference**: This guide references the [Obsidian API](https://docs.obsidian.md/Home). Familiarize yourself with the [App](https://docs.obsidian.md/Reference/TypeScript+API/App), [Vault](https://docs.obsidian.md/Reference/TypeScript+API/Vault), and [Workspace](https://docs.obsidian.md/Reference/TypeScript+API/Workspace) modules for advanced scripting. +> **Obsidian API Reference**: This guide references the [Obsidian API](https://docs.obsidian.md/Home). Familiarize yourself with the [App](https://docs.obsidian.md/Reference/TypeScript+API/App), [Vault](https://docs.obsidian.md/Reference/TypeScript+API/Vault), and [Workspace](https://docs.obsidian.md/Reference/TypeScript+API/Workspace) modules for advanced scripting. ## Basic Structure diff --git a/docs/docs/index.md b/docs/docs/index.md index be7b6047..40707675 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -3,54 +3,65 @@ sidebar_position: 1 title: Getting Started --- -## Installation +QuickAdd adds one fast command for repeatable Obsidian workflows. Use it to +create notes from templates, capture text into existing notes, run scripts, or +organize several choices behind one menu. -**This plugin is in the community plugin browser in Obsidian**. You can search for it and install it there . +## Install QuickAdd -You can also do a [manual installation](./ManualInstallation). +Install QuickAdd from Obsidian's Community Plugins browser, then enable it. -## First steps +If you cannot use the plugin browser, follow the +[manual installation guide](./ManualInstallation). -The first thing you'll want to do is add a new choice. A choice can be one of four types. +## Choose the right choice type -- [Template Choice](./Choices/TemplateChoice) - Insert templates into your vault. Works together with Obsidian template syntax and popular _Templater_ plugin, augmenting them and adding more options. -- [Capture Choice](./Choices/CaptureChoice) - Quick capture your manually written information and save it. Daily notes, work log, to-read-and-watch-later list, etc. -- [Macro Choice](./Choices/MacroChoice) - Macros to augment your workflow. Use the full power of Javascript programming language and Obsidian functions to do anything your want. E.g. [create a personal movie database](./Examples/Macro_MovieAndSeriesScript) by writing a movie name and getting the movie notes fully customized and filled with correct film's up-to-date data. -- [Multi Choice](./Choices/MultiChoice) - Folders to better organize the previous 3 choices. Usability feature, not a new functionality. -- [Share QuickAdd Packages](./Choices/Packages) - Bundle choices and scripts into a portable `.quickadd.json` file so you can reuse automations across vaults. +| If you want to... | Use this | Start here | +| --- | --- | --- | +| Create a new note from a reusable file | Template choice | [Template Choices](./Choices/TemplateChoice) | +| Append text to a journal, log, task list, or existing file | Capture choice | [Capture Choices](./Choices/CaptureChoice) | +| Run one or more Obsidian commands, scripts, or choices | Macro choice | [Macro Choices](./Choices/MacroChoice) | +| Group choices into a nested menu | Multi choice | [Multi Choices](./Choices/MultiChoice) | +| Share configured workflows across vaults | Package | [Share QuickAdd Packages](./Choices/Packages) | -In your choices, you can use [format syntax](./FormatSyntax), which is similar to the Obsidian template syntax. +Most workflows start with either a Template choice or a Capture choice. Add a +Macro choice when you need scripting, multiple steps, or data from another +plugin or API. -You could, for example, use `{{DATE}}` to get the current date. +## First workflow -QuickAdd also features a powerful [suggester system](./SuggesterSystem) that provides intelligent, fuzzy-search suggestions for files, tags, headings, and more. +1. Create a Template choice or Capture choice in QuickAdd settings. +2. Add a name you will recognize in the command palette. +3. Configure the target file, folder, template, or capture format. +4. Run `QuickAdd: Run QuickAdd` from the command palette. +5. Assign a hotkey once the workflow behaves the way you want. -## I want to... +QuickAdd choices can use [format syntax](./FormatSyntax), including values like +`{{DATE}}`, `{{VALUE}}`, and `{{FIELD:status}}`. The +[suggester system](./SuggesterSystem) provides fuzzy search for files, tags, +headings, and fields. -### Be inspired +## Common paths -Take a look at some examples... +### I want examples first -- [Capture: Add Journal Entry](docs/Examples/Capture_AddJournalEntry.md) -- [Macro: Log book to daily journal](docs/Examples/Macro_LogBookToDailyJournal.md) -- [Template: Add an Inbox Item](docs/Examples/Template_AddAnInboxItem.md) -- [Template: Create an MOC note with a link dashboard](docs/Examples/Template_CreateMOCNoteWithLinkDashboard.md) -- [Macro: Move all notes with a tag to a certain folder](docs/Examples/Macro_MoveNotesWithATagToAFolder.md) -- [Template: Automatically create a new book note with notes & highlights from Readwise](docs/Examples/Template_AutomaticBookNotesFromReadwise.md) -- [Capture: Add a task to a Kanban board](docs/Examples/Capture_AddTaskToKanbanBoard.md) -- [Macro: Easily change properties in your daily note (requires MetaEdit)](docs/Examples/Macro_ChangePropertyInDailyNotes.md) -- [Capture: Fetch tasks from Todoist and capture to a file](docs/Examples/Capture_FetchTasksFromTodoist.md) -- [Macro: Zettelizer - easily create new notes from headings while keeping the contents in the file](docs/Examples/Macro_Zettelizer.md) -- [Macro: Obsidian Map View plugin helper - insert location from address](docs/Examples/Macro_AddLocationLongLatFromAddress.md) -- [Macro: Toggl Manager - set preset Toggl Track time entries and start them from Obsidian](docs/Examples/Macro_TogglManager.md) -- [How I Read Research Papers with Obsidian and Zotero](https://bagerbach.com/blog/how-i-read-research-papers-with-obsidian-and-zotero/) -- [How I Import Literature Notes into Obsidian](https://bagerbach.com/blog/importing-source-notes-to-obsidian) -- [Macro: Fetching movies and TV shows into your vault](docs/Examples/Macro_MovieAndSeriesScript.md) +Use the [examples overview](./Examples/) to pick a complete workflow by choice +type, difficulty, prerequisites, and outcome. -### Create powerful scripts and macros to automate my workflow +Good first examples: -Take a look at the [QuickAdd API](docs/QuickAddAPI.md), [format syntax](docs/FormatSyntax.md), [inline scripts](docs/InlineScripts.md), and [macros](docs/Choices/MacroChoice.md). +- [Capture: Add Journal Entry](./Examples/Capture_AddJournalEntry) +- [Template: Add an Inbox Item](./Examples/Template_AddAnInboxItem) +- [Macro: Book Finder](./Examples/Macro_BookFinder) +- [Capture: Canvas Capture](./Examples/Capture_CanvasCapture) -### Use QuickAdd even when Obsidian is minimized / in the background +### I want to automate with scripts -You got it. Take a look at [this AutoHotKey script](./Misc/AHK_OpenQuickAddFromDesktop). +Start with the [scripting overview](./Advanced/ScriptingGuide), then move to +[User Scripts](./UserScripts) and the [QuickAdd API reference](./QuickAddAPI) +when you need exact method details. + +### I want to call QuickAdd from outside Obsidian + +Use [Obsidian URI](./Advanced/ObsidianUri) for URI-triggered workflows, or the +[QuickAdd CLI](./Advanced/CLI) for shell scripts and external automation. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 17abed7f..3bc6d1d2 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -63,13 +63,7 @@ const config = { : {}), }, }, - blog: { - showReadingTime: true, - // Please change this to your repo. - // Remove this to remove the "edit this page" links. - // editUrl: - // 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', - }, + blog: false, theme: { customCss: require.resolve('./src/css/custom.css'), }, @@ -94,22 +88,25 @@ const config = { dropdownActiveClassDisabled: true, }, { - type: 'doc', + type: 'custom-versionAwareDoc', docId: 'index', position: 'left', - label: '📚 Docs', + label: 'Docs', + activeBaseRegex: '^/docs/(next/|[0-9.]+/)?(?!(Advanced/APIOverview|QuickAddAPI|Examples/)).*', }, { - type: 'doc', + type: 'custom-versionAwareDoc', docId: 'QuickAddAPI', position: 'left', - label: '🔧 API', + label: 'API', + activeBaseRegex: '^/docs/(next/|[0-9.]+/)?(Advanced/APIOverview|QuickAddAPI)/?$', }, { - type: 'doc', + type: 'custom-versionAwareDoc', docId: 'Examples/Macro_BookFinder', position: 'left', - label: '💡 Examples', + label: 'Examples', + activeBaseRegex: '^/docs/(next/|[0-9.]+/)?Examples/', }, { href: 'https://github.com/chhoumann/quickadd', @@ -162,6 +159,7 @@ const config = { highlightSearchTermsOnTargetPage: true, explicitSearchResultPath: true, docsRouteBasePath: "/docs", + indexBlog: false, searchBarShortcutHint: false, }, ], diff --git a/docs/sidebars.js b/docs/sidebars.js index 4b9c8d28..4e8b9844 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -32,89 +32,95 @@ const sidebars = { { type: "doc", id: "index", - label: "🏠 Getting Started", + label: "Getting Started", }, { type: "category", - label: "📚 Core Concepts", + label: "Core Concepts", collapsed: false, items: [ { type: "doc", id: "Choices/TemplateChoice", - label: "📄 Template Choices", + label: "Template Choices", }, { type: "doc", id: "Choices/CaptureChoice", - label: "⚡ Capture Choices", + label: "Capture Choices", }, { type: "doc", id: "Choices/MacroChoice", - label: "🤖 Macro Choices", + label: "Macro Choices", }, { type: "doc", id: "Choices/MultiChoice", - label: "📁 Multi Choices", + label: "Multi Choices", }, { type: "doc", id: "Choices/Packages", - label: "đŸ“Ļ Share QuickAdd Packages", + label: "Share QuickAdd Packages", }, ], }, { type: "category", - label: "🔧 Features", + label: "Features", items: [ { type: "doc", id: "FormatSyntax", - label: "📝 Format Syntax", + label: "Format Syntax", }, { type: "doc", id: "GlobalVariables", - label: "🌐 Global Variables", + label: "Global Variables", }, { type: "doc", id: "InlineScripts", - label: "đŸ’ģ Inline Scripts", + label: "Inline Scripts", }, { type: "doc", id: "AIAssistant", - label: "🧠 AI Assistant", + label: "AI Assistant", }, { type: "doc", id: "TemplatePropertyTypes", - label: "📋 Template Property Types (Beta)", + label: "Template Property Types (Beta)", }, ], }, { type: "category", - label: "💡 Examples", + label: "Examples", collapsed: true, items: [ + { + type: "doc", + id: "Examples/index", + label: "Examples Overview", + }, { type: "category", - label: "📝 Capture Examples", + label: "Capture Examples", items: [ "Examples/Capture_AddJournalEntry", "Examples/Capture_AddTaskToKanbanBoard", "Examples/Capture_FetchTasksFromTodoist", "Examples/Capture_InsertBaseTemplateIntoActiveFile", + "Examples/Capture_CanvasCapture", ], }, { type: "category", - label: "📄 Template Examples", + label: "Template Examples", items: [ "Examples/Template_AddAnInboxItem", "Examples/Template_CreateMOCNoteWithLinkDashboard", @@ -123,7 +129,7 @@ const sidebars = { }, { type: "category", - label: "🤖 Macro Examples", + label: "Macro Examples", items: [ "Examples/Macro_BookFinder", "Examples/Macro_MovieAndSeriesScript", @@ -140,45 +146,55 @@ const sidebars = { }, { type: "category", - label: "🚀 Advanced", + label: "Advanced", collapsed: true, items: [ + { + type: "doc", + id: "Advanced/APIOverview", + label: "API Overview", + }, { type: "doc", id: "QuickAddAPI", - label: "📖 QuickAdd API", + label: "QuickAdd API Reference", + }, + { + type: "doc", + id: "Advanced/ScriptingGuide", + label: "Scripting Overview", }, { type: "doc", id: "UserScripts", - label: "📜 User Scripts", + label: "User Scripts Reference", }, { type: "doc", id: "Advanced/scriptsWithSettings", - label: "⚙ī¸ Scripts with Settings", + label: "Scripts with Settings", }, { type: "doc", id: "Advanced/onePageInputs", - label: "🧩 One-page Inputs", + label: "One-page Inputs", }, { type: "doc", id: "Advanced/ObsidianUri", - label: "🔗 Obsidian URI", + label: "Obsidian URI", }, ], }, { type: "category", - label: "ℹī¸ Other", + label: "Other", collapsed: true, items: [ { type: "doc", id: "ManualInstallation", - label: "💾 Manual Installation", + label: "Manual Installation", }, { type: "autogenerated", diff --git a/docs/src/components/VersionAwareDocNavbarItem.tsx b/docs/src/components/VersionAwareDocNavbarItem.tsx new file mode 100644 index 00000000..c8777ea3 --- /dev/null +++ b/docs/src/components/VersionAwareDocNavbarItem.tsx @@ -0,0 +1,47 @@ +import React from 'react'; +import {useLocation} from '@docusaurus/router'; +import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem'; + +type Props = { + activeBaseRegex?: string; + docId: string; + docsPluginId?: string; + label?: string; + mobile?: boolean; + position?: 'left' | 'right'; +}; + +export default function VersionAwareDocNavbarItem({ + activeBaseRegex, + docId, + label, + ...props +}: Props): React.JSX.Element | null { + const location = useLocation(); + const path = getVersionedDocPath(location.pathname, docId); + + return ( + + activeBaseRegex + ? new RegExp(activeBaseRegex).test(location.pathname) + : location.pathname === path + } + label={label ?? docId} + to={path} + /> + ); +} + +function getVersionedDocPath(pathname: string, docId: string): string { + const versionMatch = pathname.match(/^\/docs\/(next|[0-9.]+)(?=\/|$)/); + const docsBase = versionMatch ? `/docs/${versionMatch[1]}` : '/docs'; + + if (docId === 'index') { + return `${docsBase}/`; + } + + return `${docsBase}/${docId}`; +} diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 4ac74a13..73dd32a9 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -96,7 +96,6 @@ pre { .menu__link--active { background-color: var(--qa-accent-soft); color: var(--ifm-color-primary); - font-weight: 600; } .navbar { diff --git a/docs/src/pages/index.module.css b/docs/src/pages/index.module.css index 74157de7..f1779de5 100644 --- a/docs/src/pages/index.module.css +++ b/docs/src/pages/index.module.css @@ -27,7 +27,7 @@ ────────────────────────────────────────────────────────── */ .hero { - padding: clamp(5rem, 10vw, 8rem) 0 clamp(4rem, 8vw, 6.5rem); + padding: clamp(3.75rem, 8vw, 5.5rem) 0 clamp(3rem, 6vw, 4rem); text-align: center; position: relative; overflow: hidden; @@ -54,9 +54,9 @@ .heroLogo { display: block; - height: 96px; + height: 76px; width: auto; - margin: 0 auto 1.5rem; + margin: 0 auto 1.25rem; } .eyebrow { @@ -68,7 +68,7 @@ } .heroTitle { - font-size: clamp(2.5rem, 5.5vw + 0.5rem, 4rem); + font-size: clamp(2.4rem, 5vw + 0.5rem, 4rem); line-height: 1.05; font-weight: 600; letter-spacing: -0.028em; @@ -92,7 +92,7 @@ align-items: center; justify-content: center; gap: 0.75rem; - margin-top: 2.25rem; + margin-top: 2rem; flex-wrap: wrap; } @@ -100,7 +100,7 @@ display: inline-flex; align-items: center; gap: 0.5rem; - margin-top: 2.5rem; + margin-top: 1rem; padding: 0.5rem 0.875rem; background: var(--qa-canvas-raised); border: 1px solid var(--qa-line); @@ -109,6 +109,161 @@ color: var(--qa-ink-muted); } +.workflowPreview { + max-width: 920px; + margin: 2rem auto 0; + overflow: hidden; + text-align: left; + background: var(--qa-canvas-raised); + border: 1px solid var(--qa-line-strong); + border-radius: 14px; + box-shadow: 0 18px 60px rgba(24, 24, 27, 0.12); +} + +.previewChrome { + display: flex; + gap: 0.45rem; + padding: 0.85rem 1rem; + border-bottom: 1px solid var(--qa-line); +} + +.previewChrome span { + width: 0.68rem; + height: 0.68rem; + border-radius: 999px; + background: var(--qa-line-strong); +} + +.previewGrid { + display: grid; + grid-template-columns: 0.85fr 1.2fr 1fr; + min-height: 250px; +} + +.previewSidebar, +.previewCommand, +.previewNote { + padding: 1rem; +} + +.previewSidebar, +.previewCommand { + border-right: 1px solid var(--qa-line); +} + +.previewSidebar { + background: var(--qa-canvas); + background: color-mix(in srgb, var(--qa-canvas) 72%, var(--qa-canvas-raised)); +} + +.previewSidebarTitle, +.previewCommandLabel, +.previewNoteTitle { + margin-bottom: 0.8rem; + color: var(--qa-ink-muted); + font-size: 0.75rem; + font-weight: 700; + letter-spacing: 0.04em; + text-transform: uppercase; +} + +.previewChoice, +.previewResult { + display: flex; + align-items: center; + justify-content: space-between; + gap: 0.75rem; + padding: 0.7rem 0.75rem; + color: var(--qa-ink); + font-size: 0.875rem; + border: 1px solid transparent; + border-radius: 9px; +} + +.previewChoice + .previewChoice, +.previewResult + .previewResult { + margin-top: 0.45rem; +} + +.previewChoice:nth-child(2), +.previewResult:first-child { + background: var(--qa-accent-soft); + border-color: var(--qa-line-strong); +} + +.previewChoiceType, +.previewResult span:last-child { + color: var(--qa-accent); + font-size: 0.72rem; + font-weight: 700; + text-transform: uppercase; +} + +.previewSearch { + margin-bottom: 0.9rem; + padding: 0.8rem 0.9rem; + color: var(--qa-ink); + background: var(--qa-canvas); + border: 1px solid var(--qa-line-strong); + border-radius: 9px; + font-family: var(--ifm-font-family-monospace); + font-size: 0.82rem; +} + +.previewLine, +.previewLineShort { + height: 0.7rem; + background: var(--qa-line); + border-radius: 999px; +} + +.previewLine { + width: 88%; +} + +.previewLineShort { + width: 58%; + margin-top: 0.75rem; +} + +.previewCapture { + margin-top: 1.2rem; + padding: 0.85rem; + background: var(--qa-canvas); + border: 1px solid var(--qa-line); + border-radius: 10px; +} + +.previewCapture span { + color: var(--qa-accent); + font-family: var(--ifm-font-family-monospace); + font-size: 0.75rem; + font-weight: 700; +} + +.previewCapture p { + margin: 0.45rem 0 0; + color: var(--qa-ink-muted); + font-size: 0.88rem; + line-height: 1.5; +} + +@media (max-width: 767px) { + .workflowPreview { + margin-top: 1.5rem; + } + + .previewGrid { + grid-template-columns: 1fr; + } + + .previewSidebar, + .previewCommand { + border-right: 0; + border-bottom: 1px solid var(--qa-line); + } +} + .kbd { display: inline-flex; align-items: center; @@ -473,6 +628,8 @@ margin-top: 3rem; display: flex; justify-content: center; + gap: 0.75rem; + flex-wrap: wrap; } /* ────────────────────────────────────────────────────────── diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index bc13198d..2b0a4dd8 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -211,7 +211,7 @@ const steps = [ { title: 'Create a choice', description: - 'Open settings and add a Template, Capture, or Macro — or combine them into a Multi.', + 'Pick Template, Capture, Macro, or Multi based on what you want to automate.', }, { title: 'Hit your hotkey', @@ -220,10 +220,72 @@ const steps = [ }, ]; +const workflowRows = [ + { + type: 'Capture', + label: 'Daily log', + detail: 'Append a timestamped entry to today\u2019s note.', + }, + { + type: 'Template', + label: 'Meeting note', + detail: 'Create a note with variables, prompts, and properties.', + }, + { + type: 'Macro', + label: 'Book lookup', + detail: 'Fetch metadata, write a note, and open it in place.', + }, +]; + // ────────────────────────────────────────────────────────── // Sections // ────────────────────────────────────────────────────────── +function WorkflowPreview(): React.JSX.Element { + return ( +
+
+ + + +
+
+
+
QuickAdd
+ {workflowRows.map((row) => ( +
+ {row.type} + {row.label} +
+ ))} +
+
+
Command palette
+
QuickAdd: Run Choice
+
+ {workflowRows.map((row) => ( +
+ {row.label} + {row.type} +
+ ))} +
+
+
+
Daily note
+
+
+
+ 10:42 +

Captured idea with source link and project tag.

+
+
+
+
+ ); +} + function Hero(): React.JSX.Element { return (
@@ -239,7 +301,7 @@ function Hero(): React.JSX.Element { Supercharge Obsidian with one hotkey.

- Templates, captures, macros, and AI — bound to a single command. + Templates, captures, macros, and AI, bound to a single command. QuickAdd turns repetitive note-taking tasks into keystrokes.

@@ -249,13 +311,14 @@ function Hero(): React.JSX.Element { - Install from Obsidian → + Install from Obsidian
+
@@ -354,6 +417,9 @@ function QuickStart(): React.JSX.Element { Read the documentation + + Browse examples +
diff --git a/docs/src/theme/NavbarItem/ComponentTypes.tsx b/docs/src/theme/NavbarItem/ComponentTypes.tsx new file mode 100644 index 00000000..980297ca --- /dev/null +++ b/docs/src/theme/NavbarItem/ComponentTypes.tsx @@ -0,0 +1,7 @@ +import ComponentTypes from '@theme-original/NavbarItem/ComponentTypes'; +import VersionAwareDocNavbarItem from '../../components/VersionAwareDocNavbarItem'; + +export default { + ...ComponentTypes, + 'custom-versionAwareDoc': VersionAwareDocNavbarItem, +}; diff --git a/docs/versioned_docs/version-2.12.0/Advanced/APIOverview.md b/docs/versioned_docs/version-2.12.0/Advanced/APIOverview.md new file mode 100644 index 00000000..88eb8062 --- /dev/null +++ b/docs/versioned_docs/version-2.12.0/Advanced/APIOverview.md @@ -0,0 +1,51 @@ +--- +title: API Overview +--- + +Use the QuickAdd API when a workflow needs scripted input, file operations, +formatting, model calls, or access from another plugin. + +If you only need to create a note or append text, start with +[Template Choices](../Choices/TemplateChoice) or +[Capture Choices](../Choices/CaptureChoice). Add the API when the workflow +needs logic. + +## Where the API is available + +| Context | Access pattern | Use it for | +| --- | --- | --- | +| Macro user script | `params.quickAddApi` | Scripted macro steps | +| Inline script | `this.quickAddApi` | Small transformations inside templates or captures | +| Other plugin | `app.plugins.plugins.quickadd.api` | Calling QuickAdd from plugin code | +| Templater script | `app.plugins.plugins.quickadd.api` | Prompting or running choices from Templater | + +## Common tasks + +| Task | Method family | Reference | +| --- | --- | --- | +| Ask for text, selections, dates, or grouped inputs | User input methods | [QuickAdd API Reference](../QuickAddAPI#user-input-methods) | +| Run another choice from a script | Choice execution | [Choice Execution](../QuickAddAPI#choice-execution) | +| Read selected text or clipboard content | Utility module | [Utility Module](../QuickAddAPI#utility-module) | +| Format dates | Date module | [Date Module](../QuickAddAPI#date-module) | +| Call configured AI providers | AI module | [AI Module](../QuickAddAPI#ai-module) | +| Read field suggestions from the vault | Field suggestions module | [Field Suggestions Module](../QuickAddAPI#field-suggestions-module) | + +## Recommended path + +1. Read the [scripting overview](./ScriptingGuide) if you have not written a + QuickAdd script before. +2. Copy a working pattern from the [examples overview](../Examples/). +3. Use the [QuickAdd API reference](../QuickAddAPI) for exact signatures and + edge-case behavior. + +## Minimal macro script + +```javascript +module.exports = async ({ quickAddApi }) => { + const title = await quickAddApi.inputPrompt("Book title"); + return `# ${title}`; +}; +``` + +The returned value can be used by later macro steps or inserted through format +syntax. diff --git a/docs/versioned_docs/version-2.12.0/Advanced/ScriptingGuide.md b/docs/versioned_docs/version-2.12.0/Advanced/ScriptingGuide.md new file mode 100644 index 00000000..1563659c --- /dev/null +++ b/docs/versioned_docs/version-2.12.0/Advanced/ScriptingGuide.md @@ -0,0 +1,58 @@ +--- +title: Scripting Overview +--- + +QuickAdd scripts are JavaScript files that run inside Obsidian. They can prompt +for input, call Obsidian APIs, read other plugins, and pass values back into a +Macro choice. + +## Which scripting feature should I use? + +| 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 | + +## Basic user script shape + +```javascript +module.exports = async (params) => { + const { app, quickAddApi, variables } = params; + const title = await quickAddApi.inputPrompt("Title"); + + variables.title = title; + return title; +}; +``` + +The `params` object gives scripts access to: + +- `app`: the Obsidian app instance +- `quickAddApi`: QuickAdd's prompt, utility, AI, and execution helpers +- `variables`: values shared across macro steps + +## How values move through a macro + +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. + +## Suggested learning order + +1. [Macro Choices](../Choices/MacroChoice) for how macro steps are assembled. +2. [User Scripts](../UserScripts) for complete scripting patterns. +3. [Scripts with Settings](./scriptsWithSettings) for configurable scripts. +4. [QuickAdd API Reference](../QuickAddAPI) for exact method details. + +## Debugging + +Use `console.log` while developing scripts, then check Obsidian's developer +console. Keep scripts small enough that each step can be tested independently +before adding it to a longer macro. diff --git a/docs/versioned_docs/version-2.12.0/Choices/CaptureChoice.md b/docs/versioned_docs/version-2.12.0/Choices/CaptureChoice.md index 8e7af615..96d58bab 100644 --- a/docs/versioned_docs/version-2.12.0/Choices/CaptureChoice.md +++ b/docs/versioned_docs/version-2.12.0/Choices/CaptureChoice.md @@ -103,7 +103,8 @@ When append-link is set to **Enabled (requires active file)** and capture runs from a Canvas card without a focused Markdown editor, the capture still writes and link insertion is skipped. -A dedicated Canvas walkthrough page will return in a future update. +For a step-by-step setup, see +[Capture: Canvas Capture](../Examples/Capture_CanvasCapture). ### Canvas Capture FAQ diff --git a/docs/versioned_docs/version-2.12.0/Examples/Capture_CanvasCapture.md b/docs/versioned_docs/version-2.12.0/Examples/Capture_CanvasCapture.md new file mode 100644 index 00000000..b37ec89e --- /dev/null +++ b/docs/versioned_docs/version-2.12.0/Examples/Capture_CanvasCapture.md @@ -0,0 +1,86 @@ +--- +title: "Capture: Canvas Capture" +--- + +Canvas capture lets a Capture choice write into a selected Canvas card or into a +specific card in a specific `.canvas` file. + +## When to use this + +Use Canvas capture when your workflow starts in a visual board, but you still +want QuickAdd's capture formats, variables, and hotkeys. + +Good fits: + +- Add a timestamped note to a selected brainstorming card. +- Append a task to a project card. +- Send repeated updates to one known Canvas card. + +## Capture to the selected card + +1. Create a Capture choice. +2. Enable **Capture to active file**. +3. Open a Canvas file. +4. Select exactly one supported card. +5. Set **Write position** to **Top of file**, **Bottom of file**, or + **After line...**. +6. Run the Capture choice. + +Supported selected-card targets: + +- Text cards +- File cards that point to Markdown files + +QuickAdd aborts with a notice if no card is selected, multiple cards are +selected, or the selected card is unsupported. + +## Capture to a specific card + +1. Create a Capture choice. +2. Turn off **Capture to active file**. +3. Set **Capture To** to a `.canvas` file. +4. Choose **Target canvas node**. +5. Pick the card you want QuickAdd to write to. +6. Set a supported write position. + +This is the best option for repeatable workflows where every capture should go +to the same Canvas card. + +## Write position support + +Canvas capture supports these write positions: + +- **Top of file** +- **Bottom of file** +- **After line...** + +Canvas capture does not support cursor-based write positions: + +- **At cursor** +- **New line above cursor** +- **New line below cursor** + +If **Capture to active file** is enabled and the write position is still +**At cursor**, QuickAdd aborts instead of writing to the wrong place. + +## Append-link behavior + +When append-link is set to **Enabled (requires active file)** and capture runs +from a Canvas card without a focused Markdown editor, the capture still writes. +QuickAdd skips link insertion because there is no active Markdown file to link +from. + +## Troubleshooting + +| Symptom | Likely cause | Fix | +| --- | --- | --- | +| Capture aborts before writing | No card or multiple cards are selected | Select exactly one supported card | +| Capture aborts with cursor-position wording | The write mode is cursor-based | Use top, bottom, or after-line placement | +| Nothing is written to a file card | The file card points to a non-Markdown file | Use a Markdown file card or a text card | +| The target picker is not shown | Capture target is not a `.canvas` file | Set **Capture To** to the Canvas file path | + +## Related docs + +- [Capture Choices](../Choices/CaptureChoice) +- [Format Syntax](../FormatSyntax) +- [Template: Create an MOC Note with a Link Dashboard](./Template_CreateMOCNoteWithLinkDashboard) diff --git a/docs/versioned_docs/version-2.12.0/Examples/Template_CreateMOCNoteWithLinkDashboard.md b/docs/versioned_docs/version-2.12.0/Examples/Template_CreateMOCNoteWithLinkDashboard.md new file mode 100644 index 00000000..c5ee9eac --- /dev/null +++ b/docs/versioned_docs/version-2.12.0/Examples/Template_CreateMOCNoteWithLinkDashboard.md @@ -0,0 +1,106 @@ +--- +title: "Template: Create an MOC Note with a Link Dashboard" +--- + +Use this pattern when you want QuickAdd to create a new map-of-content note +that already contains a live Base dashboard for both backlinks and outgoing +links. + +## Why this pattern + +A Template choice can create the note and insert the dashboard in one step. +The note stays markdown, while the embedded `.base` block gives you a live view +of how that note connects to the rest of your vault. + +This works well for maps of knowledge, hub notes, topic notes, and evergreen +indexes. + +## Setup + +1. Create a reusable `.base` template, for example + `Templates/MOC Link Dashboard.base`: + +```yaml +formulas: + note_link: "file.asLink()" +properties: + formula.note_link: + displayName: Note + file.folder: + displayName: Folder + file.mtime: + displayName: Updated +views: + - type: table + name: Backlinks + filters: + and: + - 'file.ext == "md"' + - "file.hasLink(this.file)" + - "file.path != this.file.path" + order: + - formula.note_link + - file.folder + - file.mtime + - type: table + name: Outgoing links + filters: + and: + - 'file.ext == "md"' + - "this.file.hasLink(file)" + - "file.path != this.file.path" + order: + - formula.note_link + - file.folder + - file.mtime +``` + +2. Create a markdown template, for example `Templates/MOC Link Dashboard.md`: + +````markdown +--- +tags: + - moc +--- + +# {{VALUE:moc_title}} + +## Link Dashboard + +Use the view picker in this embedded base to switch between backlinks and +outgoing links for this note. + +```base +{{TEMPLATE:Templates/MOC Link Dashboard.base}} +``` + +## Notes + +- Start linking this note to related ideas. +```` + +3. Create a **Template** choice with settings like these: + +- **Template Path**: `Templates/MOC Link Dashboard.md` +- **File Name Format**: `{{VALUE:moc_title}}` +- **Create in folder**: your MOC folder, for example `MOCs` +- **Open**: enabled +- **If the target file already exists**: `Create another file` +- **New file naming**: `Increment trailing number` + +4. Run the Template choice and enter a title such as `Alpha Project`. + +## What you get + +QuickAdd creates a new markdown note with an embedded Base block. +Inside the note: + +- `Backlinks` shows notes that link to the new MOC. +- `Outgoing links` shows notes the MOC links to. +- Both views use `this.file`, so the dashboard automatically scopes itself to + the note that was just created. + +After the note exists, add links in either direction and the dashboard updates +with the current graph around that note. + +![MOC link dashboard template demo](../Images/template_moc_link_dashboard_demo.png) diff --git a/docs/versioned_docs/version-2.12.0/Examples/index.md b/docs/versioned_docs/version-2.12.0/Examples/index.md new file mode 100644 index 00000000..176d308f --- /dev/null +++ b/docs/versioned_docs/version-2.12.0/Examples/index.md @@ -0,0 +1,40 @@ +--- +title: Examples +--- + +Use these examples when you want to copy a working pattern instead of starting +from a blank choice. + +| Workflow | Choice type | Setup | Prerequisites | What it creates | +| --- | --- | --- | --- | --- | +| [Add Journal Entry](./Capture_AddJournalEntry) | Capture | Beginner | Daily note or journal file | A timestamped journal entry | +| [Add a Task to a Kanban Board](./Capture_AddTaskToKanbanBoard) | Capture | Beginner | Obsidian Kanban plugin | A task in a board section | +| [Fetch Tasks from Todoist](./Capture_FetchTasksFromTodoist) | Capture and Macro | Intermediate | Todoist API token | Imported Todoist tasks | +| [Canvas Capture](./Capture_CanvasCapture) | Capture | Intermediate | An Obsidian Canvas file | Text added to a selected or targeted card | +| [Add an Inbox Item](./Template_AddAnInboxItem) | Template | Beginner | Inbox folder or note | A new inbox note | +| [Create an MOC Note with a Link Dashboard](./Template_CreateMOCNoteWithLinkDashboard) | Template | Intermediate | Base template file | A note with an embedded Base dashboard | +| [Automatic Book Notes from Readwise](./Template_AutomaticBookNotesFromReadwise) | Template and Macro | Advanced | Readwise export script | Book notes with highlights | +| [Book Finder](./Macro_BookFinder) | Macro | Intermediate | Book lookup script | A populated book note | +| [Movie and Series Script](./Macro_MovieAndSeriesScript) | Macro | Intermediate | TMDB API key | Media notes with metadata | +| [Move Notes with a Tag](./Macro_MoveNotesWithATagToAFolder) | Macro | Intermediate | Tagged notes | Notes moved into a target folder | +| [Zettelizer](./Macro_Zettelizer) | Macro | Intermediate | Headings in an existing note | New notes split from headings | +| [Toggl Manager](./Macro_TogglManager) | Macro | Advanced | Toggl integration | Preset time entries | + +## Pick by goal + +### Capture information faster + +Start with [Add Journal Entry](./Capture_AddJournalEntry) if you want the +simplest capture flow. Move to [Canvas Capture](./Capture_CanvasCapture) when +your target is a Canvas card instead of a Markdown note. + +### Create structured notes + +Start with [Add an Inbox Item](./Template_AddAnInboxItem) for a small template. +Use [Create an MOC Note with a Link Dashboard](./Template_CreateMOCNoteWithLinkDashboard) +when you want a generated note to include a live Base dashboard. + +### Run scripted workflows + +Start with [Book Finder](./Macro_BookFinder) to see the common macro pattern: +prompt for input, call a script, write a note, and open the result. diff --git a/docs/versioned_docs/version-2.12.0/Images/template_moc_link_dashboard_demo.png b/docs/versioned_docs/version-2.12.0/Images/template_moc_link_dashboard_demo.png new file mode 100644 index 00000000..6db5e4bb Binary files /dev/null and b/docs/versioned_docs/version-2.12.0/Images/template_moc_link_dashboard_demo.png differ diff --git a/docs/versioned_docs/version-2.12.0/QuickAddAPI.md b/docs/versioned_docs/version-2.12.0/QuickAddAPI.md index f98e0b39..d84d85d8 100644 --- a/docs/versioned_docs/version-2.12.0/QuickAddAPI.md +++ b/docs/versioned_docs/version-2.12.0/QuickAddAPI.md @@ -2,6 +2,13 @@ The QuickAdd API provides a powerful interface for automating tasks in Obsidian through scripts, macros, and inline scripts. The API offers methods for user interaction, file manipulation, AI integration, and more. +:::tip Start with the overview + +If you are choosing which API surface to use, read the +[API Overview](./Advanced/APIOverview) first. This page is the full reference. + +::: + ## Accessing the API The API can be accessed in several ways: diff --git a/docs/versioned_docs/version-2.12.0/UserScripts.md b/docs/versioned_docs/version-2.12.0/UserScripts.md index 2c6eea79..c33b6f26 100644 --- a/docs/versioned_docs/version-2.12.0/UserScripts.md +++ b/docs/versioned_docs/version-2.12.0/UserScripts.md @@ -1,8 +1,15 @@ # User Scripts +:::tip New to scripting? + +Start with the [Scripting Overview](./Advanced/ScriptingGuide) for the +decision path, then use this page as the detailed reference. + +::: + User scripts are JavaScript files that extend QuickAdd's functionality with custom code. They can be used within macros to perform complex operations, integrate with external APIs, and automate sophisticated workflows. -> 📚 **Obsidian API Reference**: This guide references the [Obsidian API](https://docs.obsidian.md/Home). Familiarize yourself with the [App](https://docs.obsidian.md/Reference/TypeScript+API/App), [Vault](https://docs.obsidian.md/Reference/TypeScript+API/Vault), and [Workspace](https://docs.obsidian.md/Reference/TypeScript+API/Workspace) modules for advanced scripting. +> **Obsidian API Reference**: This guide references the [Obsidian API](https://docs.obsidian.md/Home). Familiarize yourself with the [App](https://docs.obsidian.md/Reference/TypeScript+API/App), [Vault](https://docs.obsidian.md/Reference/TypeScript+API/Vault), and [Workspace](https://docs.obsidian.md/Reference/TypeScript+API/Workspace) modules for advanced scripting. ## Basic Structure diff --git a/docs/versioned_docs/version-2.12.0/index.md b/docs/versioned_docs/version-2.12.0/index.md index 96a53583..40707675 100644 --- a/docs/versioned_docs/version-2.12.0/index.md +++ b/docs/versioned_docs/version-2.12.0/index.md @@ -3,53 +3,65 @@ sidebar_position: 1 title: Getting Started --- -## Installation +QuickAdd adds one fast command for repeatable Obsidian workflows. Use it to +create notes from templates, capture text into existing notes, run scripts, or +organize several choices behind one menu. -**This plugin is in the community plugin browser in Obsidian**. You can search for it and install it there . +## Install QuickAdd -You can also do a [manual installation](./ManualInstallation). +Install QuickAdd from Obsidian's Community Plugins browser, then enable it. -## First steps +If you cannot use the plugin browser, follow the +[manual installation guide](./ManualInstallation). -The first thing you'll want to do is add a new choice. A choice can be one of four types. +## Choose the right choice type -- [Template Choice](./Choices/TemplateChoice) - Insert templates into your vault. Works together with Obsidian template syntax and popular _Templater_ plugin, augmenting them and adding more options. -- [Capture Choice](./Choices/CaptureChoice) - Quick capture your manually written information and save it. Daily notes, work log, to-read-and-watch-later list, etc. -- [Macro Choice](./Choices/MacroChoice) - Macros to augment your workflow. Use the full power of Javascript programming language and Obsidian functions to do anything your want. E.g. [create a personal movie database](./Examples/Macro_MovieAndSeriesScript) by writing a movie name and getting the movie notes fully customized and filled with correct film's up-to-date data. -- [Multi Choice](./Choices/MultiChoice) - Folders to better organize the previous 3 choices. Usability feature, not a new functionality. -- [Share QuickAdd Packages](./Choices/Packages) - Bundle choices and scripts into a portable `.quickadd.json` file so you can reuse automations across vaults. +| If you want to... | Use this | Start here | +| --- | --- | --- | +| Create a new note from a reusable file | Template choice | [Template Choices](./Choices/TemplateChoice) | +| Append text to a journal, log, task list, or existing file | Capture choice | [Capture Choices](./Choices/CaptureChoice) | +| Run one or more Obsidian commands, scripts, or choices | Macro choice | [Macro Choices](./Choices/MacroChoice) | +| Group choices into a nested menu | Multi choice | [Multi Choices](./Choices/MultiChoice) | +| Share configured workflows across vaults | Package | [Share QuickAdd Packages](./Choices/Packages) | -In your choices, you can use [format syntax](./FormatSyntax), which is similar to the Obsidian template syntax. +Most workflows start with either a Template choice or a Capture choice. Add a +Macro choice when you need scripting, multiple steps, or data from another +plugin or API. -You could, for example, use `{{DATE}}` to get the current date. +## First workflow -QuickAdd also features a powerful [suggester system](./SuggesterSystem) that provides intelligent, fuzzy-search suggestions for files, tags, headings, and more. +1. Create a Template choice or Capture choice in QuickAdd settings. +2. Add a name you will recognize in the command palette. +3. Configure the target file, folder, template, or capture format. +4. Run `QuickAdd: Run QuickAdd` from the command palette. +5. Assign a hotkey once the workflow behaves the way you want. -## I want to... +QuickAdd choices can use [format syntax](./FormatSyntax), including values like +`{{DATE}}`, `{{VALUE}}`, and `{{FIELD:status}}`. The +[suggester system](./SuggesterSystem) provides fuzzy search for files, tags, +headings, and fields. -### Be inspired +## Common paths -Take a look at some examples... +### I want examples first -- [Capture: Add Journal Entry](docs/Examples/Capture_AddJournalEntry.md) -- [Macro: Log book to daily journal](docs/Examples/Macro_LogBookToDailyJournal.md) -- [Template: Add an Inbox Item](docs/Examples/Template_AddAnInboxItem.md) -- [Macro: Move all notes with a tag to a certain folder](docs/Examples/Macro_MoveNotesWithATagToAFolder.md) -- [Template: Automatically create a new book note with notes & highlights from Readwise](docs/Examples/Template_AutomaticBookNotesFromReadwise.md) -- [Capture: Add a task to a Kanban board](docs/Examples/Capture_AddTaskToKanbanBoard.md) -- [Macro: Easily change properties in your daily note (requires MetaEdit)](docs/Examples/Macro_ChangePropertyInDailyNotes.md) -- [Capture: Fetch tasks from Todoist and capture to a file](docs/Examples/Capture_FetchTasksFromTodoist.md) -- [Macro: Zettelizer - easily create new notes from headings while keeping the contents in the file](docs/Examples/Macro_Zettelizer.md) -- [Macro: Obsidian Map View plugin helper - insert location from address](docs/Examples/Macro_AddLocationLongLatFromAddress.md) -- [Macro: Toggl Manager - set preset Toggl Track time entries and start them from Obsidian](docs/Examples/Macro_TogglManager.md) -- [How I Read Research Papers with Obsidian and Zotero](https://bagerbach.com/blog/how-i-read-research-papers-with-obsidian-and-zotero/) -- [How I Import Literature Notes into Obsidian](https://bagerbach.com/blog/importing-source-notes-to-obsidian) -- [Macro: Fetching movies and TV shows into your vault](docs/Examples/Macro_MovieAndSeriesScript.md) +Use the [examples overview](./Examples/) to pick a complete workflow by choice +type, difficulty, prerequisites, and outcome. -### Create powerful scripts and macros to automate my workflow +Good first examples: -Take a look at the [QuickAdd API](docs/QuickAddAPI.md), [format syntax](docs/FormatSyntax.md), [inline scripts](docs/InlineScripts.md), and [macros](docs/Choices/MacroChoice.md). +- [Capture: Add Journal Entry](./Examples/Capture_AddJournalEntry) +- [Template: Add an Inbox Item](./Examples/Template_AddAnInboxItem) +- [Macro: Book Finder](./Examples/Macro_BookFinder) +- [Capture: Canvas Capture](./Examples/Capture_CanvasCapture) -### Use QuickAdd even when Obsidian is minimized / in the background +### I want to automate with scripts -You got it. Take a look at [this AutoHotKey script](./Misc/AHK_OpenQuickAddFromDesktop). +Start with the [scripting overview](./Advanced/ScriptingGuide), then move to +[User Scripts](./UserScripts) and the [QuickAdd API reference](./QuickAddAPI) +when you need exact method details. + +### I want to call QuickAdd from outside Obsidian + +Use [Obsidian URI](./Advanced/ObsidianUri) for URI-triggered workflows, or the +[QuickAdd CLI](./Advanced/CLI) for shell scripts and external automation. diff --git a/docs/versioned_sidebars/version-2.12.0-sidebars.json b/docs/versioned_sidebars/version-2.12.0-sidebars.json index 59e494ac..7c194dfb 100644 --- a/docs/versioned_sidebars/version-2.12.0-sidebars.json +++ b/docs/versioned_sidebars/version-2.12.0-sidebars.json @@ -3,97 +3,104 @@ { "type": "doc", "id": "index", - "label": "🏠 Getting Started" + "label": "Getting Started" }, { "type": "category", - "label": "📚 Core Concepts", + "label": "Core Concepts", "collapsed": false, "items": [ { "type": "doc", "id": "Choices/TemplateChoice", - "label": "📄 Template Choices" + "label": "Template Choices" }, { "type": "doc", "id": "Choices/CaptureChoice", - "label": "⚡ Capture Choices" + "label": "Capture Choices" }, { "type": "doc", "id": "Choices/MacroChoice", - "label": "🤖 Macro Choices" + "label": "Macro Choices" }, { "type": "doc", "id": "Choices/MultiChoice", - "label": "📁 Multi Choices" + "label": "Multi Choices" }, { "type": "doc", "id": "Choices/Packages", - "label": "đŸ“Ļ Share QuickAdd Packages" + "label": "Share QuickAdd Packages" } ] }, { "type": "category", - "label": "🔧 Features", + "label": "Features", "items": [ { "type": "doc", "id": "FormatSyntax", - "label": "📝 Format Syntax" + "label": "Format Syntax" }, { "type": "doc", "id": "GlobalVariables", - "label": "🌐 Global Variables" + "label": "Global Variables" }, { "type": "doc", "id": "InlineScripts", - "label": "đŸ’ģ Inline Scripts" + "label": "Inline Scripts" }, { "type": "doc", "id": "AIAssistant", - "label": "🧠 AI Assistant" + "label": "AI Assistant" }, { "type": "doc", "id": "TemplatePropertyTypes", - "label": "📋 Template Property Types (Beta)" + "label": "Template Property Types (Beta)" } ] }, { "type": "category", - "label": "💡 Examples", + "label": "Examples", "collapsed": true, "items": [ + { + "type": "doc", + "id": "Examples/index", + "label": "Examples Overview" + }, { "type": "category", - "label": "📝 Capture Examples", + "label": "Capture Examples", "items": [ "Examples/Capture_AddJournalEntry", "Examples/Capture_AddTaskToKanbanBoard", "Examples/Capture_FetchTasksFromTodoist", - "Examples/Capture_InsertBaseTemplateIntoActiveFile" + "Examples/Capture_InsertBaseTemplateIntoActiveFile", + "Examples/Capture_CanvasCapture" ] }, { "type": "category", - "label": "📄 Template Examples", + "label": "Template Examples", "items": [ "Examples/Template_AddAnInboxItem", + "Examples/Template_CreateMOCNoteWithLinkDashboard", "Examples/Template_AutomaticBookNotesFromReadwise" ] }, { "type": "category", - "label": "🤖 Macro Examples", + "label": "Macro Examples", "items": [ "Examples/Macro_BookFinder", "Examples/Macro_MovieAndSeriesScript", @@ -110,45 +117,55 @@ }, { "type": "category", - "label": "🚀 Advanced", + "label": "Advanced", "collapsed": true, "items": [ + { + "type": "doc", + "id": "Advanced/APIOverview", + "label": "API Overview" + }, { "type": "doc", "id": "QuickAddAPI", - "label": "📖 QuickAdd API" + "label": "QuickAdd API Reference" + }, + { + "type": "doc", + "id": "Advanced/ScriptingGuide", + "label": "Scripting Overview" }, { "type": "doc", "id": "UserScripts", - "label": "📜 User Scripts" + "label": "User Scripts Reference" }, { "type": "doc", "id": "Advanced/scriptsWithSettings", - "label": "⚙ī¸ Scripts with Settings" + "label": "Scripts with Settings" }, { "type": "doc", "id": "Advanced/onePageInputs", - "label": "🧩 One-page Inputs" + "label": "One-page Inputs" }, { "type": "doc", "id": "Advanced/ObsidianUri", - "label": "🔗 Obsidian URI" + "label": "Obsidian URI" } ] }, { "type": "category", - "label": "ℹī¸ Other", + "label": "Other", "collapsed": true, "items": [ { "type": "doc", "id": "ManualInstallation", - "label": "💾 Manual Installation" + "label": "Manual Installation" }, { "type": "autogenerated",