This document is a work in progress. 
## Markdown Syntax

Mnemonic Markdown is built on markdown. We aim to be largely compatible with CommonMark while adding functionality from GFM and Obsidian Markdown. Pandoc markdown also provides inspiration. 
# Retrieval Prompt Declaration
## Cloze with {{.}}

The core syntax in mnemonic markdown in `{{.}}`. This declares a retrieval prompt where the text inside the double curly braces is hidden and the paragraph around it is shown. 

For example:
```mnmd
My favorite sport is {{running}}.
```

Would create a retrieval prompt that looks like: 
> My favorite sport is [...]. 

With the answer: 
> My favorite sport is **running**. 

### Nesting Clozes

It is possible to next clozes. This is useful when you want to be able to eventually be able to remember a large chunk of information that is too long to easily recall initially. Mnemonic makrdown represents intent not implementation of the 
## Optionally Specify Scope with `[-before, after]` or `[-before]` or `[after]` following the end of the cloze. 

**By default, the retrieval prompt generated by an occlusion will show the paragraph surrounding the occlusion.** However, this is not always the right amount of context. For this reason, mnemonic markdown allows you to specify how many paragraphs before and after the paragraph with the occlusion to include in the prompt.

For example: 

```mnmd
This is one paragraph that might provide some context. 

This is another paragraph with {{an occlusion}}[-1,1]. 

This is another paragraph that may provide information required to guess the answer. 
```

Creates the retrieval prompt: 

> This is one paragraph that might provide some context. 
> 
> This is another paragraph with [...]. 
> 
> This is another paragraph that may provide information required to guess the answer. 

It would be annoying to have to write `[0, n]` or `[-n, 0]` when you wanted to augment the scope, adding only paragraphs before or after the current paragraph. 

### For clozes in markdown lists, the default scope is `[-1]`

It is extremely common to include the paragraph before the list as context. For example. 

## Hide and reveal separated occlusions together with `{{id>.}}`.

Sometimes you want to hide two non-contiguous things at the same time.

For example:
```mnmd
My two favorite foods are {{1>steak}} and {{1>honey}}.
```

Creates the following retrieval prompt: My two favorite foods are [...] and [...].

## Sequence Clozes with `{{id.order>.}}`

Mnemonic markdown provides special syntax for declaring clozes of sequences / lists of items. This can be useful for poetry. 

For example:
```mnmd
My Haiku: 

{{1.1>I want to write an}}[-1] \
{{1.2>Example poem for you}} \
{{1.3>Hopefully helpful}} \
```

Will create several retrieval prompts:

> My Haiku:
> 
> [...]
> ...

> My Haiku:
> 
> I want to write an
> [...]
> ...

> My Haiku:
> 
> I want to write an
> Example poem for you
> [...]

And finally an interactive prompt that combines all of the above, progressively revealing each cloze on click to allow the user to review the entire sequence. 

Notes: 
- In the above example the `\` serves to tell the system to preserve the newline rather than transforming it into a single (potentially wrapped) line. 
- The context modifier `[-1]` on the first applies to all the clozes. In general, for a given cloze id (in the above case, '1') context modifiers will modify all the occlusions with that id in that scope. 

## The file description and heading path is included in context. 

The file description, which defaults to the title but can be overridden with YAML front matter, as well as the 'heading path' (need to figure out what this should be called) are shown as context to each retrieval prompt. 

## Add Hints with `{{answer|hint}}`

You can add a hint that will be shown on the back of the card using the pipe `|` separator:

```mnmd
The quadratic formula is {{$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$|solves ax² + bx + c = 0}}.
```

Creates a card with:
- Front: "The quadratic formula is [...]"
- Back: Shows the formula with hint "solves ax² + bx + c = 0" below it

**Important**: The hint syntax is NOT a separate cloze type. It's a field that can be added to any cloze (basic, grouped, or sequence).

## Add Extra Information with `{{answer<extra info}}`

You can add extra information that appears on the back of the card using `<`:

```mnmd
The package manager for Python is {{pip<PyPI hosts over 400,000 packages}}.
```

**Important**:
- Extra text uses `<` with NO CLOSING `>`
- The extra text runs until the end of the cloze `}}`
- You can combine hints and extras: `{{answer|hint<extra}}`

## Combined Syntax: `{{answer|hint<extra}}`

You can use both hints and extras together:

```mnmd
Git's staging area is {{the index|where changes are prepared<also called the staging area}}.
```

## Anki IDs with `{{ankiID,groupID>answer}}` or `{{groupID,ankiID>answer}}`

After syncing, Anki IDs are automatically written back to your markdown file in base52 encoding (alphabetic only). These IDs prevent duplicates on subsequent syncs.

The order doesn't matter - you can put the Anki ID first or the group ID first:
- `{{abc,1>answer}}` - Anki ID first
- `{{1,abc>answer}}` - Group ID first

**You don't need to write these manually** - the sync tool adds them automatically 

## Define 'card' contexts with `> ?`

Using a block quote with a question mark as the first 

Example: 
```mnmd 
If I wanted to create a card context I can do the following. 

> ? 
> The clozes inside the card are the same as normal?
> 
> {{Yes}}
```

Will create a card like this: 

> The clozes inside the card are the same as normal?
> 
> [...]

Of course, it is still possible to define a question answer card by simply writing it in the document. The purpose of this syntax is to provide greater scope flexibility.

# The `<quiz/>` Tag

Though mnemonic markdown can be used to declare retrieval prompts in your notes for review in an external application such as Anki, it was designed to be an authoring format for the mnemonic medium. See Quantum Country for an example. 

The `<quiz/>` tag inserts a Quantum Country style interactive quiz into the document that gathers all retrieval prompts since the beginning of the document or since the last quiz. 

# Math with LaTeX Syntax

Mathematical equations are supported using standard LaTeX delimiters. When syncing to Anki, these are automatically converted to Anki's format:

- **Inline math**: `$E = mc^2$` → Anki's `\(E = mc^2\)` format
- **Block math**: `$$\int_0^\infty e^{-x^2} dx$$` → Anki's `\[\int_0^\infty e^{-x^2} dx\]` format

**Examples:**

```mnmd
> ?
> Einstein's famous equation is {{$E = mc^2$}}.

> ?
> The quadratic formula is {{$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$|solves ax² + bx + c = 0}}.
```

**Math works everywhere:**
- In cloze answers: `{{$\pi r^2$}}`
- In hints: `{{area|$\pi r^2$}}`
- In context text: `The formula $E = mc^2$ shows...`
- With complex nested braces: `{{$\frac{a}{b}$}}` works correctly 

# Executable Code Blocks

This is a future feature so the current description is minimal. Also, this is really most relevant to creating mnemonic media, it's not so useful for the note taking use case of mnemonic markdown

Mnemonic markdown will support several varieties of executable code blocks through the mnemonic.js library. These will be included in mnemonic markdown documents using markdown code blocks. 

Affordances of this system include: 

- Inserting code editors with runnable code and enviornments (using WASM)
- Inserting browser based TTY Linux VMs
- Allowing authors to create interactive tutorials with a sort of LeetCode experinece.

# References, Biographic References, Citations, and Footnotes / Side notes. 

Mnemonic markdown supports footnote / sidenote syntax of markdown

## Injection References

You can inject the content defined by a reference using `(^ref-name)`

## Bibtex / Biblatex citations

Configure in the front matter. 

**Unsure of the final form of this. I need to look at pandoc markdown and how it manages**

# Obsidian Markdown Features

We need to carefully consider the features of obsidian markdown and include everything that's needed since ideally we can replicate the functionality of obsidian in vscode with a lightweight plugin. 
