Metadata-Version: 2.4
Name: exam-cardforge
Version: 0.3.0
Summary: A lightweight Markdown-to-Anki toolkit for exam review workflows.
Project-URL: Homepage, https://github.com/Elysyrus/exam-cardforge
Project-URL: Issues, https://github.com/Elysyrus/exam-cardforge/issues
Project-URL: Changelog, https://github.com/Elysyrus/exam-cardforge/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/Elysyrus/exam-cardforge#readme
Author: Elysyrus
License-Expression: MIT
License-File: LICENSE
Keywords: anki,exam,flashcards,markdown,study
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Exam Cardforge

Exam Cardforge is a lightweight Markdown-to-Anki toolkit for exam review workflows.

It helps students and study groups keep notes readable in Markdown while exporting reusable flashcards for Anki. The first built-in templates target Chinese CS postgraduate entrance exam review, especially 408.

## Project positioning

Exam Cardforge is designed for people who already write course notes, wrong-question notes, or review summaries in Markdown and want a low-friction path into spaced repetition.

The project focuses on:

- human-readable Markdown syntax;
- Anki-compatible CSV export;
- exam-oriented note organization with tags, decks, and cloze cards;
- small, dependency-light Python code that new contributors can understand.

This is not a question bank. It is a conversion and validation tool for notes that users own and maintain.

## Why this project exists

Many students already write review notes in Markdown, but spaced-repetition tools usually need a more rigid card format. This project keeps notes readable while making them easy to export.

The project goal is practical and modest:

- write notes in Markdown;
- mark reusable question-answer blocks;
- export Anki-compatible CSV;
- keep the format simple enough for beginners to understand and contribute.

## Install

From PyPI, after the package is published:

```bash
python -m pip install exam-cardforge
```

From GitHub:

```bash
python -m pip install "exam-cardforge @ git+https://github.com/Elysyrus/exam-cardforge.git"
```

Verify the command is available:

```bash
exam-cardforge --help
```

## Install for local development

```bash
python -m venv .venv
.venv\Scripts\activate
python -m pip install -e . pytest
```

On macOS or Linux, activate the environment with:

```bash
source .venv/bin/activate
```

## Quick start

Create a sample note:

```bash
exam-cardforge sample -o examples/408.md
```

Build an Anki CSV:

```bash
exam-cardforge build examples/408.md -o dist/408-anki.csv
```

Show tag statistics:

```bash
exam-cardforge stats examples/408.md
```

Check whether notes are valid and detect duplicate questions:

```bash
exam-cardforge lint examples/408.md
```

## Card syntax

Write cards inside `:::card` blocks:

```markdown
:::card tags=408,data-structure,stack
Q: 栈为什么适合检查括号匹配？
A: 因为括号匹配具有“后打开的先关闭”的特点，正好对应栈的后进先出。
:::
```

Decks can be attached with `deck=`:

```markdown
:::card tags=408,os deck=408::OS
Q: 进程和程序的核心区别是什么？
A: 程序是静态代码，进程是程序在某次运行中的动态实体。
:::
```

Multi-line cards are supported:

```markdown
:::card tags=408,os
Q:
进程和程序的核心区别是什么？
A:
程序是静态代码。
进程是程序在某次运行中的动态实体，拥有运行状态和资源。
:::
```

## Cloze syntax

Use `:::cloze` blocks for Anki Cloze cards:

```markdown
:::cloze tags=408,co,memory deck=408::ComputerOrganization
局部性原理包括{{c1::时间局部性}}和{{c2::空间局部性}}。
:::
```

The generated CSV includes `Front`, `Back`, `Tags`, `Deck`, and `Note Type` columns. In Anki, map Cloze rows to the `Cloze` note type.

## Import into Anki

1. Run `exam-cardforge build`.
2. Open Anki.
3. Choose `File > Import`.
4. Select the generated CSV file.
5. Map columns as `Front`, `Back`, and `Tags`.

## Roadmap

See `ROADMAP.md` for the active maintenance plan.

## Contributing

Bug reports, syntax suggestions, parser improvements, and documentation fixes are welcome. See `CONTRIBUTING.md`.

## License

MIT
