From 142e628df79d6d0b5118ce1617ad9650035f31d5 Mon Sep 17 00:00:00 2001 From: "JLDiaz (m)" Date: Tue, 12 May 2026 22:14:31 +0200 Subject: [PATCH] Cleanup unused template files and update README --- AGENTS.md | 251 ------------------------------------------------ README.md | 97 +++---------------- main.ts | 13 --- package.json | 4 +- src/main.ts | 100 ++----------------- src/settings.ts | 36 ------- 6 files changed, 23 insertions(+), 478 deletions(-) delete mode 100644 AGENTS.md delete mode 100644 main.ts delete mode 100644 src/settings.ts diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 3f4274a..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,251 +0,0 @@ -# Obsidian community plugin - -## Project overview - -- Target: Obsidian Community Plugin (TypeScript → bundled JavaScript). -- Entry point: `main.ts` compiled to `main.js` and loaded by Obsidian. -- Required release artifacts: `main.js`, `manifest.json`, and optional `styles.css`. - -## Environment & tooling - -- Node.js: use current LTS (Node 18+ recommended). -- **Package manager: npm** (required for this sample - `package.json` defines npm scripts and dependencies). -- **Bundler: esbuild** (required for this sample - `esbuild.config.mjs` and build scripts depend on it). Alternative bundlers like Rollup or webpack are acceptable for other projects if they bundle all external dependencies into `main.js`. -- Types: `obsidian` type definitions. - -**Note**: This sample project has specific technical dependencies on npm and esbuild. If you're creating a plugin from scratch, you can choose different tools, but you'll need to replace the build configuration accordingly. - -### Install - -```bash -npm install -``` - -### Dev (watch) - -```bash -npm run dev -``` - -### Production build - -```bash -npm run build -``` - -## Linting - -- To use eslint install eslint from terminal: `npm install -g eslint` -- To use eslint to analyze this project use this command: `eslint main.ts` -- eslint will then create a report with suggestions for code improvement by file and line number. -- If your source code is in a folder, such as `src`, you can use eslint with this command to analyze all files in that folder: `eslint ./src/` - -## File & folder conventions - -- **Organize code into multiple files**: Split functionality across separate modules rather than putting everything in `main.ts`. -- Source lives in `src/`. Keep `main.ts` small and focused on plugin lifecycle (loading, unloading, registering commands). -- **Example file structure**: - ``` - src/ - main.ts # Plugin entry point, lifecycle management - settings.ts # Settings interface and defaults - commands/ # Command implementations - command1.ts - command2.ts - ui/ # UI components, modals, views - modal.ts - view.ts - utils/ # Utility functions, helpers - helpers.ts - constants.ts - types.ts # TypeScript interfaces and types - ``` -- **Do not commit build artifacts**: Never commit `node_modules/`, `main.js`, or other generated files to version control. -- Keep the plugin small. Avoid large dependencies. Prefer browser-compatible packages. -- Generated output should be placed at the plugin root or `dist/` depending on your build setup. Release artifacts must end up at the top level of the plugin folder in the vault (`main.js`, `manifest.json`, `styles.css`). - -## Manifest rules (`manifest.json`) - -- Must include (non-exhaustive): - - `id` (plugin ID; for local dev it should match the folder name) - - `name` - - `version` (Semantic Versioning `x.y.z`) - - `minAppVersion` - - `description` - - `isDesktopOnly` (boolean) - - Optional: `author`, `authorUrl`, `fundingUrl` (string or map) -- Never change `id` after release. Treat it as stable API. -- Keep `minAppVersion` accurate when using newer APIs. -- Canonical requirements are coded here: https://github.com/obsidianmd/obsidian-releases/blob/master/.github/workflows/validate-plugin-entry.yml - -## Testing - -- Manual install for testing: copy `main.js`, `manifest.json`, `styles.css` (if any) to: - ``` - /.obsidian/plugins// - ``` -- Reload Obsidian and enable the plugin in **Settings → Community plugins**. - -## Commands & settings - -- Any user-facing commands should be added via `this.addCommand(...)`. -- If the plugin has configuration, provide a settings tab and sensible defaults. -- Persist settings using `this.loadData()` / `this.saveData()`. -- Use stable command IDs; avoid renaming once released. - -## Versioning & releases - -- Bump `version` in `manifest.json` (SemVer) and update `versions.json` to map plugin version → minimum app version. -- Create a GitHub release whose tag exactly matches `manifest.json`'s `version`. Do not use a leading `v`. -- Attach `manifest.json`, `main.js`, and `styles.css` (if present) to the release as individual assets. -- After the initial release, follow the process to add/update your plugin in the community catalog as required. - -## Security, privacy, and compliance - -Follow Obsidian's **Developer Policies** and **Plugin Guidelines**. In particular: - -- Default to local/offline operation. Only make network requests when essential to the feature. -- No hidden telemetry. If you collect optional analytics or call third-party services, require explicit opt-in and document clearly in `README.md` and in settings. -- Never execute remote code, fetch and eval scripts, or auto-update plugin code outside of normal releases. -- Minimize scope: read/write only what's necessary inside the vault. Do not access files outside the vault. -- Clearly disclose any external services used, data sent, and risks. -- Respect user privacy. Do not collect vault contents, filenames, or personal information unless absolutely necessary and explicitly consented. -- Avoid deceptive patterns, ads, or spammy notifications. -- Register and clean up all DOM, app, and interval listeners using the provided `register*` helpers so the plugin unloads safely. - -## UX & copy guidelines (for UI text, commands, settings) - -- Prefer sentence case for headings, buttons, and titles. -- Use clear, action-oriented imperatives in step-by-step copy. -- Use **bold** to indicate literal UI labels. Prefer "select" for interactions. -- Use arrow notation for navigation: **Settings → Community plugins**. -- Keep in-app strings short, consistent, and free of jargon. - -## Performance - -- Keep startup light. Defer heavy work until needed. -- Avoid long-running tasks during `onload`; use lazy initialization. -- Batch disk access and avoid excessive vault scans. -- Debounce/throttle expensive operations in response to file system events. - -## Coding conventions - -- TypeScript with `"strict": true` preferred. -- **Keep `main.ts` minimal**: Focus only on plugin lifecycle (onload, onunload, addCommand calls). Delegate all feature logic to separate modules. -- **Split large files**: If any file exceeds ~200-300 lines, consider breaking it into smaller, focused modules. -- **Use clear module boundaries**: Each file should have a single, well-defined responsibility. -- Bundle everything into `main.js` (no unbundled runtime deps). -- Avoid Node/Electron APIs if you want mobile compatibility; set `isDesktopOnly` accordingly. -- Prefer `async/await` over promise chains; handle errors gracefully. - -## Mobile - -- Where feasible, test on iOS and Android. -- Don't assume desktop-only behavior unless `isDesktopOnly` is `true`. -- Avoid large in-memory structures; be mindful of memory and storage constraints. - -## Agent do/don't - -**Do** -- Add commands with stable IDs (don't rename once released). -- Provide defaults and validation in settings. -- Write idempotent code paths so reload/unload doesn't leak listeners or intervals. -- Use `this.register*` helpers for everything that needs cleanup. - -**Don't** -- Introduce network calls without an obvious user-facing reason and documentation. -- Ship features that require cloud services without clear disclosure and explicit opt-in. -- Store or transmit vault contents unless essential and consented. - -## Common tasks - -### Organize code across multiple files - -**main.ts** (minimal, lifecycle only): -```ts -import { Plugin } from "obsidian"; -import { MySettings, DEFAULT_SETTINGS } from "./settings"; -import { registerCommands } from "./commands"; - -export default class MyPlugin extends Plugin { - settings: MySettings; - - async onload() { - this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData()); - registerCommands(this); - } -} -``` - -**settings.ts**: -```ts -export interface MySettings { - enabled: boolean; - apiKey: string; -} - -export const DEFAULT_SETTINGS: MySettings = { - enabled: true, - apiKey: "", -}; -``` - -**commands/index.ts**: -```ts -import { Plugin } from "obsidian"; -import { doSomething } from "./my-command"; - -export function registerCommands(plugin: Plugin) { - plugin.addCommand({ - id: "do-something", - name: "Do something", - callback: () => doSomething(plugin), - }); -} -``` - -### Add a command - -```ts -this.addCommand({ - id: "your-command-id", - name: "Do the thing", - callback: () => this.doTheThing(), -}); -``` - -### Persist settings - -```ts -interface MySettings { enabled: boolean } -const DEFAULT_SETTINGS: MySettings = { enabled: true }; - -async onload() { - this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData()); - await this.saveData(this.settings); -} -``` - -### Register listeners safely - -```ts -this.registerEvent(this.app.workspace.on("file-open", f => { /* ... */ })); -this.registerDomEvent(window, "resize", () => { /* ... */ }); -this.registerInterval(window.setInterval(() => { /* ... */ }, 1000)); -``` - -## Troubleshooting - -- Plugin doesn't load after build: ensure `main.js` and `manifest.json` are at the top level of the plugin folder under `/.obsidian/plugins//`. -- Build issues: if `main.js` is missing, run `npm run build` or `npm run dev` to compile your TypeScript source code. -- Commands not appearing: verify `addCommand` runs after `onload` and IDs are unique. -- Settings not persisting: ensure `loadData`/`saveData` are awaited and you re-render the UI after changes. -- Mobile-only issues: confirm you're not using desktop-only APIs; check `isDesktopOnly` and adjust. - -## References - -- Obsidian sample plugin: https://github.com/obsidianmd/obsidian-sample-plugin -- API documentation: https://docs.obsidian.md -- Developer policies: https://docs.obsidian.md/Developer+policies -- Plugin guidelines: https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines -- Style guide: https://help.obsidian.md/style-guide diff --git a/README.md b/README.md index 8ffa20e..a877418 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,21 @@ -# Obsidian Sample Plugin +# Obsidian Copy Protocol Plugin -This is a sample plugin for Obsidian (https://obsidian.md). +This is a simple plugin for Obsidian that registers a custom `obsidian://copy` protocol. +It allows you to create internal links that, when clicked, will silently copy a specific text to your clipboard without opening any external applications or showing popups. -This project uses TypeScript to provide type checking and documentation. -The repo depends on the latest plugin API (obsidian.d.ts) in TypeScript Definition format, which contains TSDoc comments describing what it does. +## Usage -This sample plugin demonstrates some of the basic functionality the plugin API can do. -- Adds a ribbon icon, which shows a Notice when clicked. -- Adds a command "Open modal (simple)" which opens a Modal. -- Adds a plugin setting tab to the settings page. -- Registers a global click event and output 'click' to the console. -- Registers a global interval which logs 'setInterval' to the console. +Create a link using the following format: +`[Link text](obsidian://copy?text=Your%20text%20here)` -## First time developing plugins? +When you click the link, "Your text here" will be copied to your clipboard, and a small notice will appear to confirm the action. -Quick starting guide for new plugin devs: +Note: Remember to URL-encode your text (e.g., use `%20` instead of spaces). -- Check if [someone already developed a plugin for what you want](https://obsidian.md/plugins)! There might be an existing plugin similar enough that you can partner up with. -- Make a copy of this repo as a template with the "Use this template" button (login to GitHub if you don't see it). -- Clone your repo to a local development folder. For convenience, you can place this folder in your `.obsidian/plugins/your-plugin-name` folder. -- Install NodeJS, then run `npm i` in the command line under your repo folder. -- Run `npm run dev` to compile your plugin from `main.ts` to `main.js`. -- Make changes to `main.ts` (or create new `.ts` files). Those changes should be automatically compiled into `main.js`. -- Reload Obsidian to load the new version of your plugin. -- Enable plugin in settings window. -- For updates to the Obsidian API run `npm update` in the command line under your repo folder. +## Installation -## Releasing new releases - -- Update your `manifest.json` with your new version number, such as `1.0.1`, and the minimum Obsidian version required for your latest release. -- Update your `versions.json` file with `"new-plugin-version": "minimum-obsidian-version"` so older versions of Obsidian can download an older version of your plugin that's compatible. -- Create new GitHub release using your new version number as the "Tag version". Use the exact version number, don't include a prefix `v`. See here for an example: https://github.com/obsidianmd/obsidian-sample-plugin/releases -- Upload the files `manifest.json`, `main.js`, `styles.css` as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release. -- Publish the release. - -> You can simplify the version bump process by running `npm version patch`, `npm version minor` or `npm version major` after updating `minAppVersion` manually in `manifest.json`. -> The command will bump version in `manifest.json` and `package.json`, and add the entry for the new version to `versions.json` - -## Adding your plugin to the community plugin list - -- Check the [plugin guidelines](https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines). -- Publish an initial version. -- Make sure you have a `README.md` file in the root of your repo. -- Make a pull request at https://github.com/obsidianmd/obsidian-releases to add your plugin. - -## How to use - -- Clone this repo. -- Make sure your NodeJS is at least v16 (`node --version`). -- `npm i` or `yarn` to install dependencies. -- `npm run dev` to start compilation in watch mode. - -## Manually installing the plugin - -- Copy over `main.js`, `styles.css`, `manifest.json` to your vault `VaultFolder/.obsidian/plugins/your-plugin-id/`. - -## Improve code quality with eslint -- [ESLint](https://eslint.org/) is a tool that analyzes your code to quickly find problems. You can run ESLint against your plugin to find common bugs and ways to improve your code. -- This project already has eslint preconfigured, you can invoke a check by running`npm run lint` -- Together with a custom eslint [plugin](https://github.com/obsidianmd/eslint-plugin) for Obsidan specific code guidelines. -- A GitHub action is preconfigured to automatically lint every commit on all branches. - -## Funding URL - -You can include funding URLs where people who use your plugin can financially support it. - -The simple way is to set the `fundingUrl` field to your link in your `manifest.json` file: - -```json -{ - "fundingUrl": "https://buymeacoffee.com" -} -``` - -If you have multiple URLs, you can also do: - -```json -{ - "fundingUrl": { - "Buy Me a Coffee": "https://buymeacoffee.com", - "GitHub Sponsor": "https://github.com/sponsors", - "Patreon": "https://www.patreon.com/" - } -} -``` - -## API Documentation - -See https://docs.obsidian.md +You can install this plugin via [BRAT](https://github.com/TfTHacker/obsidian42-brat): +1. Open the BRAT settings in Obsidian. +2. Click "Add Beta plugin". +3. Paste the repository URL: `jldiaz/obsidian-copy-protocol-plugin`. +4. Enable the plugin in your Community Plugins list. diff --git a/main.ts b/main.ts deleted file mode 100644 index 6b34b26..0000000 --- a/main.ts +++ /dev/null @@ -1,13 +0,0 @@ -import { Plugin, Notice } from 'obsidian'; - -export default class CopyProtocolPlugin extends Plugin { - async onload() { - this.registerObsidianProtocolHandler('copy', (params) => { - if (params.text) { - const query = decodeURIComponent(params.text); - navigator.clipboard.writeText(query); - new Notice(`Copied to clipboard!`); - } - }); - } -} diff --git a/package.json b/package.json index 17268d7..9d901ce 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { - "name": "obsidian-sample-plugin", + "name": "obsidian-copy-protocol-plugin", "version": "1.0.0", - "description": "This is a sample plugin for Obsidian (https://obsidian.md)", + "description": "An Obsidian plugin that adds support for copying text via an obsidian://copy?text=... protocol.", "main": "main.js", "type": "module", "scripts": { diff --git a/src/main.ts b/src/main.ts index 6fe0c83..6b34b26 100644 --- a/src/main.ts +++ b/src/main.ts @@ -1,99 +1,13 @@ -import {App, Editor, MarkdownView, Modal, Notice, Plugin} from 'obsidian'; -import {DEFAULT_SETTINGS, MyPluginSettings, SampleSettingTab} from "./settings"; - -// Remember to rename these classes and interfaces! - -export default class MyPlugin extends Plugin { - settings: MyPluginSettings; +import { Plugin, Notice } from 'obsidian'; +export default class CopyProtocolPlugin extends Plugin { async onload() { - await this.loadSettings(); - - // This creates an icon in the left ribbon. - this.addRibbonIcon('dice', 'Sample', (evt: MouseEvent) => { - // Called when the user clicks the icon. - new Notice('This is a notice!'); - }); - - // This adds a status bar item to the bottom of the app. Does not work on mobile apps. - const statusBarItemEl = this.addStatusBarItem(); - statusBarItemEl.setText('Status bar text'); - - // This adds a simple command that can be triggered anywhere - this.addCommand({ - id: 'open-modal-simple', - name: 'Open modal (simple)', - callback: () => { - new SampleModal(this.app).open(); + this.registerObsidianProtocolHandler('copy', (params) => { + if (params.text) { + const query = decodeURIComponent(params.text); + navigator.clipboard.writeText(query); + new Notice(`Copied to clipboard!`); } }); - // This adds an editor command that can perform some operation on the current editor instance - this.addCommand({ - id: 'replace-selected', - name: 'Replace selected content', - editorCallback: (editor: Editor, view: MarkdownView) => { - editor.replaceSelection('Sample editor command'); - } - }); - // This adds a complex command that can check whether the current state of the app allows execution of the command - this.addCommand({ - id: 'open-modal-complex', - name: 'Open modal (complex)', - checkCallback: (checking: boolean) => { - // Conditions to check - const markdownView = this.app.workspace.getActiveViewOfType(MarkdownView); - if (markdownView) { - // If checking is true, we're simply "checking" if the command can be run. - // If checking is false, then we want to actually perform the operation. - if (!checking) { - new SampleModal(this.app).open(); - } - - // This command will only show up in Command Palette when the check function returns true - return true; - } - return false; - } - }); - - // This adds a settings tab so the user can configure various aspects of the plugin - this.addSettingTab(new SampleSettingTab(this.app, this)); - - // If the plugin hooks up any global DOM events (on parts of the app that doesn't belong to this plugin) - // Using this function will automatically remove the event listener when this plugin is disabled. - this.registerDomEvent(document, 'click', (evt: MouseEvent) => { - new Notice("Click"); - }); - - // When registering intervals, this function will automatically clear the interval when the plugin is disabled. - this.registerInterval(window.setInterval(() => console.log('setInterval'), 5 * 60 * 1000)); - - } - - onunload() { - } - - async loadSettings() { - this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData() as Partial); - } - - async saveSettings() { - await this.saveData(this.settings); - } -} - -class SampleModal extends Modal { - constructor(app: App) { - super(app); - } - - onOpen() { - let {contentEl} = this; - contentEl.setText('Woah!'); - } - - onClose() { - const {contentEl} = this; - contentEl.empty(); } } diff --git a/src/settings.ts b/src/settings.ts deleted file mode 100644 index 352121e..0000000 --- a/src/settings.ts +++ /dev/null @@ -1,36 +0,0 @@ -import {App, PluginSettingTab, Setting} from "obsidian"; -import MyPlugin from "./main"; - -export interface MyPluginSettings { - mySetting: string; -} - -export const DEFAULT_SETTINGS: MyPluginSettings = { - mySetting: 'default' -} - -export class SampleSettingTab extends PluginSettingTab { - plugin: MyPlugin; - - constructor(app: App, plugin: MyPlugin) { - super(app, plugin); - this.plugin = plugin; - } - - display(): void { - const {containerEl} = this; - - containerEl.empty(); - - new Setting(containerEl) - .setName('Settings #1') - .setDesc('It\'s a secret') - .addText(text => text - .setPlaceholder('Enter your secret') - .setValue(this.plugin.settings.mySetting) - .onChange(async (value) => { - this.plugin.settings.mySetting = value; - await this.plugin.saveSettings(); - })); - } -}