{SUBJECT_NAME} - Flashcards

Spaced repetition flashcards for {SUBJECT_NAME} compatible with the flashcards app.

📁 Structure

.
├── flashcards/          # Markdown flashcard files
│   └── example.md
├── sources/             # Parsed references
│   └── example/
│       ├── content.json # Document content
│       ├── images/      # Extracted figures from PDF
│       └── figures/     # Curated figures for flashcards
│           ├── diagram.png
│           └── manifest.json  # Generated by analyze-figures
├── references/
│   └── example.pdf
└── README.md

🚀 Quick Start: Generate Flashcards from PDFs

Step 1: Set Up Authentication

flashcards auth

Step 2: Add Your Reference

cp /path/to/example.pdf references/

Step 3: Process reference → Structured Content

flashcards process references/example.pdf

This extracts text and figures into sources/example/:

• content.json — parsed document structure
• images/ — extracted figures

Step 3.5: Add Curated Figures (Optional)

Add your own figures for visual flashcards:

mkdir -p sources/example/figures
# Add your figures (use descriptive names)
# Multi-part figures: use -1, -2 suffix (e.g., diagram-1.png, diagram-2.png)
flashcards analyze-figures sources/example

Figure naming:

• Single figures: descriptive names (vector-diagram.png, circuit-example.png)
• Multi-part figures: common prefix + -1, -2 suffix (force-body-1.png, force-body-2.png)

The analyze-figures command generates manifest.json with AI-readable descriptions and optionally renames files with descriptive names.

Step 4: Generate Flashcards

flashcards generate sources/example

Options:

--template <subject>    # Use subject-specific writing guide (physics, chemistry, etc.)
--prereqs <file.md>     # Reference prior flashcards for continuity
--order <number>        # Set order in TOML frontmatter
--tags <tag1> <tag2>    # Add topic tags

📋 CLI Reference

Command	Description
flashcards auth	Set up authentication
flashcards process <pdf> --output <name>	Extract PDF content to sources/
flashcards analyze-figures <source>	Analyze figures, generate manifest, rename files
flashcards generate <source> --output <name>	Generate flashcards from source
flashcards show-prompt <file>	Reconstruct generation prompt
flashcards create <name>	Create a new deck

analyze-figures options: --force (recompute), --no-rename (skip renaming), --verbose

🎯 Using These Flashcards

1. Clone this repository or add it as a deck in the flashcards app
2. Study using the flashcards app
3. Review regularly using the FSRS spaced repetition algorithm

Adding as a Deck

In the flashcards app, add this repository URL as a GitHub deck, or clone locally and add as a local collection.

✍️ Contributing

Contributions welcome! Follow these guidelines:

Flashcard Quality Guidelines

• One concept per card (atomicity)
• Use appropriate format:
  • C: for cloze deletions (facts, formulas)
  • Q:/A: for questions and answers (concepts, "why" questions)
  • P:/S: for problems with step-by-step solutions (IPEE framework)
• Self-contained cards: Each card should make sense on its own
• Define variables: Every formula must define its symbols

See the general writing guide for comprehensive principles.

📂 Figure References

Figures are stored in sources/<name>/ and referenced from flashcards using relative paths:

• images/ — automatically extracted from PDFs
• figures/ — curated figures you add manually

Q: What does this diagram show?

![Diagram description](../sources/example/figures/vector-diagram.png)

A: [Description of what the diagram illustrates]

Since flashcard files are in flashcards/, use ../sources/ to navigate up one directory.

🔗 Related Repositories

• Flashcards App: thomasrribeiro/flashcards
• Organization: thomasrribeiro-flashcards

📄 License

Educational materials for personal use. Reference materials in references/ are subject to their original copyright.

---

Created: {DATE} Structure: Follows flashcards project conventions