docs: add readme

filipesilva · Jan 12, 2023 · cb7349a · cb7349a
1 parent 8a083de
commit cb7349a
Show file tree

Hide file tree

Showing 10 changed files with 87 additions and 80 deletions.
diff --git a/README.md b/README.md
@@ -1,35 +1,93 @@
-# Obsidian Sample Plugin
+# Obsidian Babashka
 
-This is a sample plugin for Obsidian (https://obsidian.md).
+Obsidian Babashka is a plugin for [Obsidian](https://obsidian.md/) that lets you run [Clojure](https://clojure.org/) and [ClojureScript](https://clojurescript.org/) code blocks via [Babashka](https://babashka.org/) and [Node Babashka](https://github.com/babashka/nbb) respectively.
 
-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.
+The main usecase for this plugin is scripting in the context of your vault documents.
 
-**Note:** The Obsidian API is still in early alpha and is subject to change at any time!
+You need to set absolute paths for `bb` (for clojure), and/or `nbb` and `node` (for clojurescript) in the plugin settings before executing code blocks.
+You can find these paths using the `where` command in the terminal.
 
-This sample plugin demonstrates some of the basic functionality the plugin API can do.
-- Changes the default font color to red using `styles.css`.
-- Adds a ribbon icon, which shows a Notice when clicked.
-- Adds a command "Open Sample Modal" 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.
 
-## First time developing plugins?
+## Features
 
-Quick starting guide for new plugin devs:
+### Execute codeblock
 
-- 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.
+![execute-codeblock](./docs/execute-codeblock.gif)
 
-## Releasing new releases
+
+### Execute codeblock and print outside
+
+![execute-codeblock-and-print-outside](./docs/execute-codeblock-and-print-outside.gif)
+
+
+### Vault bindings for current file
+
+![vault-bindings](./docs/vault-bindings.jpg)
+
+
+### Blocking async support in both clj and cljs due to Babashka being awesome
+
+![async](./docs/async.jpg)
+
+
+### Supports dependencies via `bb.edn` and `nbb.edn`
+
+You'll find a [`bb.edn`](https://book.babashka.org/#project-setup) and [`nbb.edn`](https://github.com/babashka/nbb#dependencies) in the vault babashka dir.
+It defaults to `.babashka`, but configurable in the settings.
+
+You can configure source paths, and add dependencies to these files that will be available in the code blocks.
+NPM packages installed in this directory will also be available to CLJS codeblocks.
+
+If you're syncing the vault and installing a lot of dependencies, you might want to set the vault babashka dir to an absolute path outside the vault, so that the dependencies aren't synced.
+
+
+## How it works
+
+When you call the execute command, the plugin will:
+- use a regex to find all code blocks in the file
+- if you're not in a clojure or clojurescript block, tell you via a notice, and stop
+- otherwise call `bb -e "..."` with your code instead of `...`, with `"` escaped, and with cwd set to the vault babashka dir
+- cap the output at 1000 lines if you have that setting turned on
+- print the output as comments inside the codeblock, or as just text outside, depending on which execute command you ran
+- execution errors and stderr show as notices, and in the developer console
+
+The `vault-bindings` namespace is in `.babashka/gen/vault-bindings.cljc`, and is auto generated each time you execute a code block:
+
+```clojure
+(ns vault-bindings)
+;; This file is auto-generated by the Babashka plugin when you execute a codeblock.
+;; Don't edit it directly, it will be overwritten.
+(def *vault-name* "personal")
+(def *vault-path* "/Users/filipesilva/Library/Mobile Documents/iCloud~md~obsidian/Documents/personal")
+(def *vault-babashka-path* "/Users/filipesilva/Library/Mobile Documents/iCloud~md~obsidian/Documents/personal/.babashka")
+(def *last-folder-path* "/Users/filipesilva/Library/Mobile Documents/iCloud~md~obsidian/Documents/personal//")
+(def *last-file-name* "scratch.md")
+(def *last-file-path* "/Users/filipesilva/Library/Mobile Documents/iCloud~md~obsidian/Documents/personal/scratch.md")
+```
+
+## Roadmap
+
+I'd like to add a command to start a REPL, and a command to kill all running processes initiated by the plugin.
+
+
+## Prior Art
+
+- https://github.com/victorb/obsidian-wielder
+- https://github.com/twibiral/obsidian-execute-code
+
+
+## Development instructions
+
+### How to run the plugin locally
+
+- Clone this repo.
+- Either clone into the plugin folder, or symlink it there, e.g. `ln -s /path/to/obsidian-babashka /path/to/your/vault/.obsidian/plugins/obsidian-babashka`.
+- `npm i` or `yarn` to install dependencies.
+- `npm run dev` to start compilation in watch mode.
+- Reload Obsidian to load the plugin initially.
+- Disable/Enable the plugin in community plugins to reload it after making changes.
+
+### 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.
@@ -40,56 +98,14 @@ Quick starting guide for new plugin devs:
 > 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 https://github.com/obsidianmd/obsidian-releases/blob/master/plugin-review.md
 - 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.
-- `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 (optional)
-- [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. 
-- To use eslint with this project, make sure to 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\`
-
-## 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
 

diff --git a/docs/async.jpg b/docs/async.jpg
diff --git a/docs/execute-codeblock-and-print-outside.gif b/docs/execute-codeblock-and-print-outside.gif
diff --git a/docs/execute-codeblock.gif b/docs/execute-codeblock.gif
diff --git a/docs/vault-bindings.jpg b/docs/vault-bindings.jpg
diff --git a/main.ts b/main.ts
@@ -257,7 +257,6 @@ class SettingTab extends PluginSettingTab {
 
 		containerEl.empty();
 
-		// TODO: toggle instead hardcoded to 1k
 		containerEl.createEl('h2', { text: 'General' });
 		this.addToggleSetting('Limit output', `Output will be truncated after ${DEFAULT_OUTPUT_LIMIT} characters.`, 'limitOutput');
 

diff --git a/manifest.json b/manifest.json
@@ -2,7 +2,7 @@
 	"id": "obsidian-babashka",
 	"name": "Babashka",
 	"version": "1.0.0",
-	"minAppVersion": "0.15.0",
+	"minAppVersion": "1.1.9",
 	"description": "Run Clojure(Script) codeblocks in Babashka.",
 	"author": "Filipe Silva",
 	"authorUrl": "https://github.com/filipesilva",

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
-	"name": "obsidian-sample-plugin",
+	"name": "obsidian-babashka",
 	"version": "1.0.0",
-	"description": "This is a sample plugin for Obsidian (https://obsidian.md)",
+	"description": "Babashka plugin for Obsidian",
 	"main": "main.js",
 	"scripts": {
 		"dev": "node esbuild.config.mjs",

diff --git a/styles.css b/styles.css
diff --git a/versions.json b/versions.json
@@ -1,3 +1,3 @@
 {
-	"1.0.0": "0.15.0"
+	"1.0.0": "1.1.9"
 }