hashcards

Hashcards uses a lightweight Markdown-based notation for different card types:

Basic (Question/Answer)

Use Q: and A: prefixes. Content can span multiple lines.

Q: What is the question?
A: What is the answer?

Cloze (Fill-in-the-blank)

Use C: and wrap the hidden text in square brackets [].

C: An [agonist] is a ligand that [activates it].

Term-Definition

A shorthand for cloze cards. Use T: for the term and D: for the definition.

T: lithification
D: The process of turning loose sediment into rock.

Separators

You can use horizontal rules (---) to visually separate cards in a file.

Q: Question?
A: Answer.

C: This is a [cloze] card.

T: term
D: definition.

Use standard Markdown syntax for images and audio.

Path Resolution:

• Relative to deck: By default, paths are relative to the Markdown file containing the card (e.g., ![](images/photo.png)).
• Relative to collection root: Prefix the path with @/ to resolve from the root directory (e.g., ![](@/Assets/photo.png)). This ensures links work even if the deck file is moved.

Audio Example:

Q: How do you pronounce this?
A: ![](audio/file.mp3)

![](@/Images/diagram.png)

You can install hashcards using several methods depending on your environment:

• Cargo: If you have Rust's package manager installed, run:

  cargo install hashcards

• Arch Linux: Available via the AUR as hashcards-bin.
• Pre-built Binaries: Download them from the releases page.
• Build from source:

  git clone https://github.com/eudoxia0/hashcards.git
  cd hashcards
  make
  sudo make install

Hashcards supports LaTeX via KaTeX.

• Inline math: Use $ ... $.
• Display math: Use $$ ... $$.

To define custom LaTeX macros, create a macros.tex file in your collection root. Macros can use arguments like #1, #2, etc.

Example:

Q: What is $\binom{n}{k}$?
A: From a set of size $n$, we can choose $k$ subsets.

C: The amount of substance $n$ is defined as:

$$
n = \frac{N}{N_A}
$$

When interacting with the drill session (via the web interface or API), the system processes several specific actions. Some actions correspond to FSRS (Free Spaced Repetition Scheduler) grades, while others manage the session state.

Grading Actions

These actions are used to rate your memory of a card and update its performance metrics:

• Forgot: Marks the card as forgotten.
• Hard: Marks the card as difficult.
• Good: Marks the card as a successful review.
• Easy: Marks the card as an easy review.

Session Management Actions

• Reveal: Shows the answer/back of the current card.
• Undo: Reverts the last review, restoring the card to the front of the queue and rolling back performance changes.
• End: Manually finishes the current session and saves progress.
• Shutdown: Shuts down the application (only available after a session has been finished).

In a drill session, a Review represents the outcome of interacting with a specific Card. It captures the temporal and algorithmic state of the review using FSRS (Free Spaced Repetition Scheduler) metrics.

Key properties of a Review include:

• card: The card being reviewed.
• reviewed_at: The timestamp of the review.
• grade: The Grade assigned (e.g., Grade::Forgot, Grade::Hard).
• stability, difficulty: FSRS-specific metrics.
• interval_raw and interval_days: The calculated spacing for the next review.
• due_date: The scheduled date for the next review.

A review is considered for repetition if the should_repeat() method returns true, which occurs when the grade is Grade::Forgot or Grade::Hard.

The Cache is an in-memory storage mechanism used during drill sessions to track changes to card performance. Instead of writing every change to the database immediately, changes are held in this cache and only persisted when the session ends.

This design provides two key benefits:

1. Undo Support: It makes implementing undo functionality simpler by managing changes in memory.
2. Session Abort Safety: Users can abort a study session without any of the changes made during that session being persisted to the database.

// The Cache stores a mapping of CardHash to Performance
// Changes are only persisted to the database at the end of a session.

By default, the deck name is the filename (sans extension). To use a different name (useful for grouping multiple files under one deck name), use TOML frontmatter at the top of your Markdown file:

---
name = "My Custom Deck Name"
---

C: This card belongs to [My Custom Deck Name].

---
name = "Medicine"
---

C: The mitochondria is the [powerhouse] of the cell.

You can specify metadata at the top of a Markdown deck file using TOML frontmatter delimited by ---. Currently, the parser supports a name field to override the default deck name (which defaults to the filename).

Example:

---
name = "My Custom Deck"
---

Q: Question?
A: Answer.

The drill server's grading interface is determined by the AnswerControls setting. This affects which grading buttons and keyboard shortcuts are available during a session:

Note: The Reveal action (Shortcut: space) is always available before grading a card.