ob2qualkard/README.md

# Obsidian to QualKard (ob2qualkard)

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.

## How a card is written

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).

````markdown
```qualcard
When is judicial review available?

Only on a concrete case or controversy brought by a party with standing.
```
````

- 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).

## Pushing

Run the command **"Push this note to QualKard"** (command palette or the editor
right-click menu):

- **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.

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.

## Settings

| 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 |

The target board must already be set up as a QualKard study board; otherwise the task is
created but never treated as a card.

## Network and privacy

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.

## Build and install

```
pnpm install
make install VAULT=/abs/path/to/your/vault
```

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.

## License

GPL-3.0-or-later. Copyright (C) 2026 Ruben Carlo Benante <rcb@beco.cc>.