OpenStudy

From Markdown notes to deliberate practice.

OpenStudy is a Markdown-first AI study workspace for turning raw notes and imported documents into structured questions, focused practice, explainable feedback, and a study loop you can keep using every day.

English · 简体中文 · Contributing · Code of Conduct · Releases · Changelog · Report an Issue

Why OpenStudy

OpenStudy is built around a very specific frustration: we already have the notes, the excerpts, and the question drafts, but turning them into a repeatable practice system still feels too manual.

Instead of treating a Markdown note set as a dead asset, OpenStudy turns it into a structured practice space:

• Start from Markdown-first study material and editable question-bank content.
• Use AI to clean up and normalize multiple-choice, fill-in-the-blank, and short-answer questions.
• Practice inside a focused quiz flow with keyboard-friendly navigation.
• Ask AI in context when you need explanation instead of just an answer.
• Review mistakes, retry questions, and track progress over time.
• Generate study insights manually when you actually want them, not every time you open the page.

What You Can Do

• Markdown-first by default: keep your source material editable, durable, and versionable.
• Bring documents into Markdown, not into a black box: convert PDF, Word, PowerPoint, HTML, CSV, and more through MarkItDown, then keep working in a clean Markdown workflow.
• AI cleanup, not AI chaos: turn rough notes into usable questions without giving up structure.
• Practice built for repetition: move fast with shortcuts, retries, and bottom-pinned core actions.
• Ask AI in the right moment: get hints, explanations, and reasoning exactly where confusion appears.
• Review that compounds: revisit wrong answers, track weak spots, and generate insights only when needed.
• Ready to distribute: ship installers for Windows, Apple Silicon macOS, and Linux from one release flow.

At A Glance

1. Import Markdown: start from a Markdown question bank and bring it straight into a durable study workspace.
2. Review and practice: inspect the source, launch a focused quiz flow, and use keyboard-friendly actions for repetition.
3. Ask AI in context: get hints or explanations without leaving the current question.
4. Close the loop: revisit mistakes in Wrong Book and generate Insights manually when you are ready to reflect.

Demo

The demo above follows the real app loop: Import Markdown -> Review Source -> Practice -> Ask AI -> Wrong Book -> Redo -> Generate Insights.

Markdown-First, Not Markdown-Only

OpenStudy keeps Markdown as the editable source of truth, but it does not force every source file to begin as Markdown.

MarkItDown works as the import gateway for formats such as PDF, Word, PowerPoint, HTML, CSV, Excel, EPUB, and selected image-based inputs. The converted result then flows back into the same Markdown-first review, identification, practice, and retry pipeline.

Key CLI checks:

node bin/openstudy.mjs doctor
node bin/openstudy.mjs setup markitdown
node bin/openstudy.mjs convert ./notes.pdf -o ./notes.md
node bin/openstudy.mjs ingest ./slides.pptx --title "Algorithms Review"

Standards

OpenStudy uses a two-layer standard:

• Author-facing Markdown is the format you edit, diff, review, and keep in Git.
• Canonical JSON is the internal structured contract for validation, automation, and future integrations.

The canonical schema lives at schemas/openstudy-question-set.schema.json, and the CLI can print or locate it with openstudy standards schema --print.

Markdown is still opinionated. We use one stable question layout so AI cleanup, parsing, retry flows, and review all behave predictably.

• Field labels stay ASCII: Type:, Answer:, Explanation:, optionally Topic: and Tags:.
• Allowed Type values are choice, multiple, judge, fill, short, and code.
• Type: should appear inside each question block before Answer:.
• For code-analysis questions, keep the code block with the stem and place Type: below the options, not above the code.

choice - Multiple Choice

## Multiple Choice

### 1. Which JUnit 5 API is used to verify an exception?

- A. assertThrows
- B. assertAll
- C. assertEquals
- D. assertNotNull

Type: choice
Answer: A
Explanation: JUnit 5 uses assertThrows to verify exceptions.

multiple - Multiple Select

## Multiple Select

### 1. Which of the following are JUnit 5 annotations?

- A. @Test
- B. @BeforeAll
- C. @Override
- D. @Disabled

Type: multiple
Answer: ABD
Explanation: @Override is a Java annotation, not a JUnit 5 annotation.

judge - True or False

## True or False

### 1. @WebMvcTest is a full Spring integration testing annotation.

- [ ] True
- [ ] False

Type: judge
Answer: False
Explanation: @WebMvcTest only loads the web layer slice.

fill - Fill in the Blank

## Fill in the Blank

### 1. The Spring Boot annotation used for controller tests is ____.

Type: fill
Answer: @WebMvcTest
Explanation: It is used for web-layer slice testing.

short - Short Answer

## Short Answer

### 1. Briefly describe the basic TDD workflow.

Type: short
Answer: Red, green, refactor.
Explanation: A semantically equivalent answer is acceptable.

code - Code Analysis

## Code Analysis

### 1. Read the code below. Which description is correct?

```java
@WebMvcTest(UserController.class)
public class UserApiTest {
    @Autowired
    private MockMvc mockMvc;
}
```

- A. It loads every Spring bean
- B. It is used for controller slice testing
- C. It automatically launches a browser
- D. It is only used for database migration

Type: code
Answer: B
Explanation: @WebMvcTest is used for controller slice testing.

CLI

The desktop app and CLI share the same service layer, database, and question standard. The CLI is meant for conversion, ingestion, validation, export, automation, and LLM-backed study workflows.

Health, setup, and conversion

openstudy doctor
openstudy setup markitdown [--spec "markitdown[all]"]
openstudy convert <file> [--output out.md] [--lang zh|en]
openstudy ingest <file> [--title TITLE] [--lang zh|en] [--skip-identify]

Documents and Markdown

openstudy docs list
openstudy docs import <file> [--title TITLE]
openstudy markdown get <docId> [--output out.md]
openstudy markdown set <docId> <file.md>

Questions and standards

openstudy questions identify <docId> [--lang zh|en]
openstudy questions list <docId> [--format json|table]
openstudy questions export <docId> [--format json|markdown] [--output file]
openstudy validate <file.(md|json)> [--format markdown|json]
openstudy exam import <docId> <file.(md|json)>
openstudy standards schema [--print]
openstudy standards markdown [--lang zh|en]

Practice, wrong book, and stats

openstudy attempts add <questionId> --answer "..." [--correct]
openstudy attempts wrong
openstudy attempts recent [--limit 20]
openstudy attempts clear --all | --doc <docId> | --question <questionId>
openstudy stats overall
openstudy stats doc <docId>

AI and settings

openstudy ai test
openstudy ai ask <questionId> --prompt "..."
openstudy ai grade <questionId> --answer "..." [--save]
openstudy ai insights [--doc <docId>] [--limit 80] [--language zh|en]
openstudy settings show
openstudy settings llm --provider deepseek --model deepseek-chat [--base-url URL] [--api-key KEY] [--vision-model MODEL]

Downloads

Download platform builds from the Releases page.

Platform	Package	Architecture	Notes
Windows	.exe installer	x64	Unsigned installers may show SmartScreen on first launch.
macOS	.dmg	arm64	Apple Silicon only. Unsigned apps may require right-click → Open on first launch.
Linux	.AppImage, .deb	x64	Pick the format that best fits your distribution.

AI Providers

OpenStudy supports multiple LLM backends for question extraction, grading, AI chat, and insights:

• DeepSeek
• OpenAI-compatible providers
• OpenAI
• Anthropic
• Ollama
• xAI-compatible setups through the OpenAI-style endpoint flow

DeepSeek is a practical default for Chinese study content because it works well with structured JSON output and keeps costs low.

Development

Requirements: Node.js 20+ and a working desktop build environment for Electron.

npm install
npm run dev

Quality checks:

npm run typecheck
npm run test:unit

Production packaging:

npm run dist:win
npm run dist:mac
npm run dist:linux

Build outputs are written to release/<version>/.

TODO List

• Keep Markdown as the canonical editable study format.
• Support document ingestion through MarkItDown and a shared CLI workflow.
• Ship normalized installers for Windows, Apple Silicon macOS, and Linux.
• Improve OCR- and vision-heavy import quality beyond the base MarkItDown environment.
• Add smarter handling for very large study sets that exceed model-context limits.

Contributing

Contributions, bug reports, UX suggestions, and packaging improvements are welcome. See CONTRIBUTING.md before opening a pull request.

License

MIT