beco/ob2qualkard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ob2qualkard v0.2 test alpha

Browse Source
This commit is contained in:
Ruben Carlo Benante
2026-08-05 21:11:46 -03:00
parent 43a66d604c
commit 7085576313
13 changed files with 308 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
README.md
View File

@@ -1,92 +1,75 @@
# Obsidian Sample Plugin
# Obsidian to QualKard (ob2qualkard)
This is a sample plugin for Obsidian (https://obsidian.md).
Push a flashcard from an Obsidian note to a [QualKard](https://code.beco.cc/beco/kanboard)
spaced-repetition board on Kanboard. One command, one card, one direction: your notes
stay the source of truth; nothing is ever synced back.
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.
## How a card is written
This sample plugin demonstrates some of the basic functionality the plugin API can do.
A card lives inside a fenced code block with the info string `qualcard`. The **first
blank line** splits it: the first paragraph becomes the card's **front** (the Kanboard
task title / prompt), and everything after the blank line becomes the **back** (the task
description / answer).
- 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 outputs a Notice on click.
- Registers a global interval which logs 'setInterval' to the console.
````markdown
```qualcard
When is judicial review available?
## First time developing plugins?
Only on a concrete case or controversy brought by a party with standing.
```
````
Quick starting guide for new plugin devs:
- The front is a single line (wrapped lines are joined with spaces), because Kanboard
task titles are single-line.
- The back keeps its Markdown, including paragraph breaks.
- A note may contain **any number** of `qualcard` blocks; the surrounding prose is never
sent.
- A block with **no blank line** has no answer and is skipped (a flashcard needs both
sides).
- 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 `src/main.ts` to `main.js`.
- Make changes to `src/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.
## Pushing
## Releasing new releases
Run the command **"Push this note to QualKard"** (command palette or the editor
right-click menu):
- 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.
- **One** `qualcard` block in the note -> it is pushed, wherever the cursor is.
- **Several** blocks -> the block **under the cursor** is pushed. If the cursor is not
inside any block, nothing is pushed and you are asked to place it.
> 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`
Pushing is deliberate and creates a new card each time (no de-duplication). On the
QualKard board the new task is automatically adopted as a fresh "new" card in the Drafts
column.
## Adding your plugin to the community plugin list
## Settings
- 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.
| Setting | Meaning |
|---|---|
| Kanboard URL | Base URL of your Kanboard, e.g. `https://organon.beco.cc` |
| API username | Kanboard user whose personal API token is used (e.g. `drbeco`) |
| API token | That user's personal API token |
| Study board | Display name of the QualKard-enabled board to push to |
## How to use
The target board must already be set up as a QualKard study board; otherwise the task is
created but never treated as a card.
- Clone this repo.
- Make sure your NodeJS is at least v18 (`node --version`).
- `npm i` to install dependencies.
- `npm run dev` to start compilation in watch mode.
## Network and privacy
## Manually installing the plugin
This plugin makes network requests **only** when you run the push command, and sends
**only** the front/back text of the single block you push -- never any other note
content. The API token is stored in this vault's `.obsidian` data (`data.json`) in plain
text; if you sync or back up your vault, keep that in mind and do not publish it.
- Copy over `main.js`, `styles.css`, `manifest.json` to your vault `VaultFolder/.obsidian/plugins/your-plugin-id/`.
## Build and install
## 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"
}
```
pnpm install
make install VAULT=/abs/path/to/your/vault
```
If you have multiple URLs, you can also do:
Then fully restart Obsidian (the reload button does not reliably reload a changed plugin)
and enable **Obsidian to QualKard**. You can also install it with
[BRAT](https://github.com/TfTHacker/obsidian42-brat) from the GitHub mirror.
```json
{
"fundingUrl": {
"Buy Me a Coffee": "https://buymeacoffee.com",
"GitHub Sponsor": "https://github.com/sponsors",
"Patreon": "https://www.patreon.com/"
}
}
```
## License
## API Documentation
See https://docs.obsidian.md
GPL-3.0-or-later. Copyright (C) 2026 Ruben Carlo Benante <rcb@beco.cc>.