# Wizard

An Obsidian plugin that turns a template into a step-by-step questionnaire and writes the
answers straight into your note — one question per screen, saved as you type.

The wizard itself is generic: what it asks comes entirely from a template file, so the same
plugin can drive a sermon prep flow, an intake form, a retrospective, or a decision checklist.

![The wizard's title page](https://raw.githubusercontent.com/driekeerJ/wizard/main/docs/intro.png)

## Features

- **One question per screen** — a title page, then your questions, then Finish
- **Question types** — free text, single choice (radio), multiple choice (checkboxes)
- **Conditional questions** — show a question only when another question has a given answer
- **Required questions** — Next stays disabled until the question is answered
- **Saves as you type** — answers land in the note within milliseconds, so nothing is lost if
  Obsidian closes or you hit the X
- **Resume where you left off** — reopening the wizard restores every answer and jumps to the
  first unanswered question
- **The note is the source of truth** — edit an answer in the note by hand and the wizard picks
  it up next time
- **Clean, readable notes** — plain headings and text, no hidden markers or HTML comments
- **Works on desktop and mobile**

## Screenshots

| | |
| --- | --- |
| ![A text question](https://raw.githubusercontent.com/driekeerJ/wizard/main/docs/text-question.png) | ![A single choice question](https://raw.githubusercontent.com/driekeerJ/wizard/main/docs/option.png) |
| A required text question — **Next** stays disabled until it is answered | Single choice: pick exactly one option |
| ![A multiple choice question](https://raw.githubusercontent.com/driekeerJ/wizard/main/docs/multiple-choice.png) | ![The resulting note](https://raw.githubusercontent.com/driekeerJ/wizard/main/docs/output.png) |
| Multiple choice: pick as many as you like | The answers in your note — plain headings and text |

## How it works

1. Open the note the answers should go into and place your cursor where the answers should be
   inserted.
2. Run **Wizard: Start** from the command palette.
3. Pick a template. The plugin remembers your choice in the note's frontmatter, so next time the
   wizard opens straight away.
4. Answer the questions. Everything is saved while you go.
5. Press **Finish** — or just close the wizard. Both keep your answers.

## Template format

A template is a Markdown file whose name ends in `.wizard.md`, stored in the template folder
(`Templates/Wizards` by default, configurable in the settings). The definition lives in a
` ```yaml ` code block in the body; anything outside that block is ignored, so you can document
your template right next to it.

````markdown
# Example wizard

Anything outside the yaml block is plain text and is ignored.

```yaml
title: This is the title
subtitle: some explanation

questions:
  - id: 12c4bb86-e062-43a0-83c2-bd78ec8a5f21
    question: Question 1?
    description: >
      Optional explanation, shown in a collapsible block under the question.
      Add `expanded: true` to show it open right away.
    type: text
    required: true

  - id: 556f4fc3-f285-4a5e-914c-aa515349dc83
    question: Question 2?
    type: option
    options:
      - id: bdebda08-9031-4f5b-9ce5-20276eb6e40b
        label: Option 1
      - id: a6a76be1-01e4-40f7-a03c-3062a6367289
        label: Option 2
      - id: 05b6b426-4515-414f-bccd-18cd0cd11ce8
        label: Option 3

  - id: 6dac2905-582a-41f3-b1e8-df46d177b388
    question: Question 3?
    type: multiple
    condition:
      - questionId: 556f4fc3-f285-4a5e-914c-aa515349dc83
        optionIds:
          - 05b6b426-4515-414f-bccd-18cd0cd11ce8
    options:
      - id: 3f2a1b90-1111-4a2b-8c3d-000000000001
        label: Option 1
      - id: 3f2a1b90-1111-4a2b-8c3d-000000000002
        label: Option 2
```
````

### Fields

| Field | Where | Required | Meaning |
| --- | --- | --- | --- |
| `title` | top level | yes | Shown on the title page |
| `subtitle` | top level | no | Explanation under the title |
| `questions` | top level | yes | The questions, in the order they are asked |
| `id` | question | yes | Stable identifier, used by conditions. Never reuse one |
| `question` | question | yes | The question text — also the heading in the note |
| `description` | question | no | Extra explanation, shown in a collapsible block under the question |
| `expanded` | question | no | `true` shows that explanation open instead of collapsed |
| `type` | question | yes | `text`, `option` or `multiple` |
| `required` | question | no | `true` blocks Next until the question is answered |
| `options` | question | for `option` / `multiple` | The choices |
| `condition` | question | no | Only show this question when the conditions hold |

### Conditions

A condition points at another question and a set of options:

```yaml
condition:
  - questionId: <id of another question>
    optionIds:
      - <option id>
      - <another option id>
```

- Multiple `optionIds` within one condition are **OR**-ed — any of them makes it true.
- Multiple conditions on one question are **AND**-ed — all of them must hold.
- A question whose parent question is itself hidden stays hidden too.

Answers to hidden questions are kept, so nothing is lost when a question disappears and comes
back.

## What ends up in your note

![The resulting note](https://raw.githubusercontent.com/driekeerJ/wizard/main/docs/output.png)

```markdown
---
wizard: Templates/Wizards/Example.wizard.md
---

## Question 1?
The answer given

## Question 2?
Option 3

## Question 3?
- Option 1
- Option 3
```

- `wizard:` in the frontmatter links the note to its template.
- Each question becomes a level 2 heading; the answer sits underneath it.
- **An answer runs until the first blank line.** Text you write below a blank line is yours and
  is never touched or overwritten by the wizard. The trade-off: an answer itself cannot contain
  a blank line — line breaks inside a text answer are collapsed to single newlines when saved.
- Because headings are the anchor, **question texts must be unique** within a template, and
  renaming a heading by hand disconnects that answer.

## Settings

- **Template folder** — where the plugin looks for `*.wizard.md` files. Defaults to
  `Templates/Wizards`.

## Installation

### From this repository (manual)

1. Download `main.js`, `manifest.json` and `styles.css` from the latest release.
2. Put them in `<your vault>/.obsidian/plugins/wizard/`.
3. Enable **Wizard** under Settings → Community plugins.

## Development

```bash
npm install
npm run dev       # watch build
npm run build     # type-check and production build
npm run release   # bump, tag, push and publish a GitHub release
```

`npm run release` takes an optional argument: a version (`npm run release 0.2.0`) or
`patch` / `minor` / `major`. Without an argument it releases the version currently in
`manifest.json`. It needs a clean working tree.

The script bumps the version files, tags and pushes. A GitHub Actions workflow then builds the
plugin, publishes the release with `main.js`, `manifest.json` and `styles.css`, and signs those
assets with [build provenance attestations](https://docs.github.com/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds),
so anyone can verify they were built from this repository.

The source lives in `src/`:

| File | Responsibility |
| --- | --- |
| `main.ts` | Plugin entry point, commands, saving |
| `parser.ts` | Reads and validates a template |
| `wizardModal.ts` | The wizard UI |
| `document.ts` | Reading answers from and writing answers to a note |
| `answers.ts` | Answer state and condition evaluation |
| `pickers.ts` | Template picker and error dialog |
| `settings.ts` | Settings tab |

`main.js` is a build artifact and is not checked in — build it locally or take it from a
release.

## Roadmap

- More question types (date, number, dropdown)
- A command to insert a new question with a generated id

## Contributing

Ideas, issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md)
for how to set up a development vault and which design decisions to keep intact.

## License

MIT — see [LICENSE](LICENSE).