feat: support markdown user scripts

Author: chhoumann

docs/docs/Choices/MacroChoice.md

@@ -115,17 +115,21 @@ The **Paste with format** command preserves rich formatting when pasting content
 
 ## User Scripts
 
-User scripts are JavaScript files that extend macro functionality. They have access to:
+User scripts are JavaScript code stored in `.js` files (or markdown notes with a
+single `js`/`javascript` code block). They have access to:
 - The Obsidian app object
 - The QuickAdd API
 - A variables object for passing data between commands
 
 :::warning Script Placement Requirements
 
-User scripts (.js files) must be placed in your Obsidian vault, but **NOT** in the `.obsidian` directory or in hidden folders (folders starting with a dot).
+User scripts (`.js` files, or `.md` notes with a single `js`/`javascript` code
+block) must be placed in your Obsidian vault, but **NOT** in the `.obsidian`
+directory or in hidden folders (folders starting with a dot).
 
 ✅ **Valid locations:**
 - `/scripts/myScript.js`
+- `/scripts/myScript.md`
 - `/_quickadd/scripts/myScript.js`
 - `/macros/utilities/helper.js`
 - `/my-custom-folder/script.js`
@@ -143,6 +147,17 @@ Scripts placed in the `.obsidian` directory or hidden folders are intentionally
 
 :::
 
+### Markdown-Backed Scripts (.md)
+
+QuickAdd also supports scripts stored inside markdown notes. The note must
+contain **exactly one** fenced `js` or `javascript` code block; everything else
+is ignored. If you need to target an exported member, include it in the command
+name:
+
+```
+script.md::exportName
+```
+
 ### Basic Script Structure
 
 ```javascript

docs/docs/UserScripts.md

@@ -1,6 +1,9 @@
 # User Scripts
 
-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.
+User scripts are JavaScript code stored in `.js` files (or markdown notes with a
+single `js`/`javascript` code block). 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.
 
@@ -33,6 +36,26 @@ async function start(params, settings) {
 }
 ```
 
+## Markdown-Backed Scripts (.md)
+
+QuickAdd can also run scripts stored inside markdown notes. To do this, the note
+must contain **exactly one** fenced code block tagged `js` or `javascript`
+(case-insensitive). All other text in the note is ignored.
+
+Example note:
+
+````md
+# My Script Note
+
+This note documents what the script does.
+
+```js
+module.exports = async (params) => {
+    // Your code here
+};
+```
+````
+
 ## Script Parameters
 
 The script receives two parameters:

src/constants.ts

@@ -93,6 +93,7 @@ export const FILE_NAME_OF_CURRENT_FILE_REGEX = new RegExp(/{{FILENAMECURRENT}}/i
 export const MARKDOWN_FILE_EXTENSION_REGEX = new RegExp(/\.md$/);
 export const CANVAS_FILE_EXTENSION_REGEX = new RegExp(/\.canvas$/);
 export const JAVASCRIPT_FILE_EXTENSION_REGEX = new RegExp(/\.js$/);
+export const USER_SCRIPT_FILE_EXTENSION_REGEX = new RegExp(/\.(js|md)$/i);
 export const MACRO_REGEX = new RegExp(/{{MACRO:([^\n\r}]*)}}/i);
 export const TEMPLATE_REGEX = new RegExp(/{{TEMPLATE:([^\n\r}]*.md)}}/i);
 export const GLOBAL_VAR_REGEX = new RegExp(/{{GLOBAL_VAR:([^\n\r}]*)}}/i);

src/gui/MacroGUIs/CommandSequenceEditor.ts

@@ -16,7 +16,7 @@ import { WaitCommand } from "../../types/macros/QuickCommands/WaitCommand";
 import { NestedChoiceCommand } from "../../types/macros/QuickCommands/NestedChoiceCommand";
 import { CaptureChoice } from "../../types/choices/CaptureChoice";
 import { TemplateChoice } from "../../types/choices/TemplateChoice";
-import { JAVASCRIPT_FILE_EXTENSION_REGEX } from "../../constants";
+import { USER_SCRIPT_FILE_EXTENSION_REGEX } from "../../constants";
 import { UserScript } from "../../types/macros/UserScript";
 import { GenericTextSuggester } from "../suggesters/genericTextSuggester";
 import GenericYesNoPrompt from "../GenericYesNoPrompt/GenericYesNoPrompt";
@@ -114,7 +114,7 @@ export class CommandSequenceEditor {
 	private loadJavascriptFiles(): void {
 		this.javascriptFiles = this.app.vault
 			.getFiles()
-			.filter((file) => JAVASCRIPT_FILE_EXTENSION_REGEX.test(file.path));
+			.filter((file) => USER_SCRIPT_FILE_EXTENSION_REGEX.test(file.path));
 	}
 
 	private renderCommandList(parent: HTMLElement) {
@@ -335,9 +335,38 @@ export class CommandSequenceEditor {
 			const value: string = input.getValue();
 			const scriptBasename = getUserScriptMemberAccess(value).basename;
 
-			const file = this.javascriptFiles.find(
+			if (!scriptBasename) return;
+
+			const byPath = this.javascriptFiles.find(
+				(f) => f.path === scriptBasename
+			);
+			if (byPath) {
+				this.addCommand(new UserScript(value, byPath.path));
+				input.setValue("");
+				if (addButton) {
+					addButton.buttonEl.style.display = "none";
+				}
+				return;
+			}
+
+			const byName = this.javascriptFiles.filter(
+				(f) => f.name === scriptBasename
+			);
+			if (byName.length === 1) {
+				this.addCommand(new UserScript(value, byName[0].path));
+				input.setValue("");
+				if (addButton) {
+					addButton.buttonEl.style.display = "none";
+				}
+				return;
+			}
+
+			const byBasename = this.javascriptFiles.filter(
 				(f) => f.basename === scriptBasename
 			);
+			if (byBasename.length !== 1) return;
+
+			const file = byBasename[0];
 			if (!file) return;
 
 			this.addCommand(new UserScript(value, file.path));
@@ -359,7 +388,7 @@ export class CommandSequenceEditor {
 				new GenericTextSuggester(
 					this.app,
 					textComponent.inputEl,
-					this.javascriptFiles.map((f) => f.basename)
+					this.javascriptFiles.map((f) => f.name)
 				);
 
 				textComponent.inputEl.addEventListener(
@@ -378,7 +407,7 @@ export class CommandSequenceEditor {
 					.onClick(async () => {
 						const selected = await this.showScriptPicker();
 						if (selected) {
-							this.addCommand(new UserScript(selected.basename, selected.path));
+							this.addCommand(new UserScript(selected.name, selected.path));
 						}
 					})
 			)
@@ -494,20 +523,20 @@ export class CommandSequenceEditor {
 			return null;
 		}
 
-		const scriptNames = this.javascriptFiles.map((f) => f.basename);
+		const scriptNames = this.javascriptFiles.map((f) => f.path);
 		const selected = await InputSuggester.Suggest(
 			this.app,
 			scriptNames,
 			scriptNames,
 			{
-				placeholder: "Select a JavaScript file",
-				emptyStateText: "No .js files found in your vault",
+				placeholder: "Select a script file",
+				emptyStateText: "No .js or .md files found in your vault",
 			}
 		);
 
 		if (!selected) return null;
 
-		return this.javascriptFiles.find((f) => f.basename === selected) ?? null;
+		return this.javascriptFiles.find((f) => f.path === selected) ?? null;
 	}
 
 	private addCommand(command: ICommand) {

src/gui/MacroGUIs/ConditionalCommandSettingsModal.ts

@@ -11,9 +11,7 @@ import {
 	getDefaultValueTypeForOperator,
 	requiresExpectedValue,
 } from "../../utils/conditionalHelpers";
-import {
-	JAVASCRIPT_FILE_EXTENSION_REGEX
-} from "../../constants";
+import { USER_SCRIPT_FILE_EXTENSION_REGEX } from "../../constants";
 import InputSuggester from "../InputSuggester/inputSuggester";
 import { showNoScriptsFoundNotice } from "./noScriptsFoundNotice";
 
@@ -80,7 +78,7 @@ export class ConditionalCommandSettingsModal extends Modal {
 	private loadJavascriptFiles() {
 		this.javascriptFiles = this.app.vault
 			.getFiles()
-			.filter((file) => JAVASCRIPT_FILE_EXTENSION_REGEX.test(file.path));
+			.filter((file) => USER_SCRIPT_FILE_EXTENSION_REGEX.test(file.path));
 	}
 
 	private reload() {
@@ -244,7 +242,7 @@ export class ConditionalCommandSettingsModal extends Modal {
 
 		new Setting(this.contentEl)
 			.setName("Script path")
-			.setDesc("Vault-relative path to the JavaScript file.")
+			.setDesc("Vault-relative path to the script file.")
 			.addText((text) => {
 				input = text;
 				text
@@ -270,8 +268,8 @@ export class ConditionalCommandSettingsModal extends Modal {
 							scriptNames,
 							scriptNames,
 							{
-								placeholder: "Select a JavaScript file",
-								emptyStateText: "No .js files found in your vault",
+								placeholder: "Select a script file",
+								emptyStateText: "No .js or .md files found in your vault",
 							}
 						);
 

src/gui/MacroGUIs/noScriptsFoundNotice.ts

@@ -1,21 +1,21 @@
 import { Notice } from "obsidian";
 
 /**
- * Shows a notice to the user when no JavaScript files are found in their vault.
+ * Shows a notice to the user when no script files are found in their vault.
  * Provides helpful guidance on where to place scripts and links to documentation.
  */
 export function showNoScriptsFoundNotice(): void {
 	const notice = new Notice("", 10000);
 	const messageEl = notice.messageEl ?? notice.containerEl ?? notice.noticeEl;
 	messageEl.empty();
 	messageEl.createEl("div", {
-		text: "No JavaScript files found",
+		text: "No script files found",
 		cls: "quickadd-notice-title",
 	});
 
 	const content = messageEl.createDiv();
 	content.createEl("div", {
-		text: "QuickAdd cannot find any .js files in your vault.",
+		text: "QuickAdd cannot find any .js or .md files in your vault.",
 	});
 	content.createEl("br");
 	content.createEl("div", { text: "Please make sure your scripts are:" });
@@ -25,7 +25,7 @@ export function showNoScriptsFoundNotice(): void {
 	content.createEl("div", {
 		text: "✓ Not in hidden folders (starting with a dot)",
 	});
-	content.createEl("div", { text: "✓ Have a .js extension" });
+	content.createEl("div", { text: "✓ Have a .js or .md extension" });
 	content.createEl("br");
 
 	const link = content.createEl("a", {

src/utilityObsidian.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, it } from "vitest";
 import { __test } from "./utilityObsidian";
 
-const { convertLinkToEmbed, extractMarkdownLinkTarget } = __test;
+const {
+	convertLinkToEmbed,
+	extractMarkdownLinkTarget,
+	extractSingleJavascriptCodeBlock,
+} = __test;
 
 describe("convertLinkToEmbed", () => {
 	it("converts wiki links to embeds", () => {
@@ -70,4 +74,61 @@ describe("extractMarkdownLinkTarget", () => {
 	it("returns null for empty targets", () => {
 		expect(extractMarkdownLinkTarget("[Label]()")).toBeNull();
 	});
-});
+});
+
+describe("extractSingleJavascriptCodeBlock", () => {
+	it("returns code when exactly one js block is present", () => {
+		const note = [
+			"# Script Note",
+			"",
+			"```js",
+			"module.exports = async () => {};",
+			"```",
+		].join("\n");
+
+		expect(extractSingleJavascriptCodeBlock(note)).toEqual({
+			code: "module.exports = async () => {};",
+		});
+	});
+
+	it("ignores non-js fences when one js block is present", () => {
+		const note = [
+			"```json",
+			"{ \"ok\": true }",
+			"```",
+			"",
+			"```javascript",
+			"module.exports = async () => {};",
+			"```",
+		].join("\n");
+
+		expect(extractSingleJavascriptCodeBlock(note)?.code).toBe(
+			"module.exports = async () => {};"
+		);
+	});
+
+	it("returns null when there are multiple js blocks", () => {
+		const note = [
+			"```js",
+			"const a = 1;",
+			"```",
+			"```javascript",
+			"const b = 2;",
+			"```",
+		].join("\n");
+
+		expect(extractSingleJavascriptCodeBlock(note)).toBeNull();
+	});
+
+	it("returns null when no js blocks exist", () => {
+		const note = [
+			"# Script Note",
+			"",
+			"```json",
+			"{ \"ok\": true }",
+			"```",
+		].join("\n");
+
+		expect(extractSingleJavascriptCodeBlock(note)).toBeNull();
+	});
+});