README.md

Flashdown

Flashdown is an interactive Node.js flashcard app with a CLI (command line interface) which stores all its data in human readable and editable plain text files.

Screenshots

State of the project

I'm not actively developing this at the moment but I'm happy for people to use it, fork it, or do whatever they want with it!

I think this is pretty safe, but use at your own risk!

How to use

You will need Node.js installed on your system (mainly tested on 16.13.1 but any recent version should work).

To install:

npm install -g flashdown

To run:

npx flashdown

Command line options

• --file <filename> specify location of a single Flashdown (.fd) file to use instead of importing all the Flashdown (.fd) files within the ~/.flashdown directory
• --test don't write your progress to the practice record (.fdr) files
• --stats display some stats generated by the spaced repetition algorithm for each card during your session
• --cram <multiplier> enable cram mode multiplier, use any number greater than 1 to decrease the card scheduling intervals and therefore increase your rate of study (default value 2)

Synchronization between different devices

Here are two approaches you could take:

1. Install Flashdown on a VPS which you can ssh into from any device. (I'm currently using the free version of Termius to do this via my iPhone.)
2. Ensure the ~/.flashdown folder is kept in sync across your different machines. I don't actually do this so don't have any concrete recommendations but I think something like Dropbox could work.

Flashdown is a spaced repetition flashcard app, what is that exactly?

It's a digital version of the physical flashcards you may have used to study a bunch of facts. The idea is to look at one side of the card, which may be a question like: "How old is the Earth?" and then try to guess the answer on the back, in this case "4.5 billion years". Within a Flashdown (.fd) file you'd represent simply in just a single line:

How old is the Earth?: 4.5 billion years

Another type of card may have a word on one side, for example "Epistemology", and on the back would be the definition "the study of knowledge acquisition", which again in Flashdown would look like this:

Epistemology: the study of knowledge acquisition

Yet another use is for language learning in which case you might put the same word in different languages on each side of the card, for example:

Hola: Hello

One way in which apps like Flashdown improve upon physical flashcards is in their use of a scheduling algorithm. Basically, after being shown the flip side of a card you are asked whether you remembered the answer. If you self-report having remembered the information, then this card will be scheduled for review some time X days in the future. If you report having not remembered the information, then the card will be repeated within your current practice session, and then will be scheduled for a time less than X days in the future (i.e. less than the time you'd wait had you remembered it correctly). Each time you remember a fact correctly, it will be scheduled at progressively longer and longer time intervals into the future. These intervals may start at 1 day and can end up being over a year after you've shown that you can remember it accurately a few times. This way, you won't waste too much time studying facts which you find very easy, and you can optimize your time by focussing more on the things which you are struggling with. (See also: Forgetting curve)

The Flashdown (.fd) plain text file format

All your flashcards are specified in human readable plain text files which make them easy to review and edit using your favorite text editor. The use of a simple plain text file format also makes it simple to use the same files with your own scripts or apps.

See /exampleFlashcards for some example .fd files. The format is very simple and is illustrated below:

# Topic header

front of card A: back of card A
  note attached to card A which is indented by 2 spaces and will be shown after the flip side of the flashcard is revealed while practicing

In practice sessions you will study the card in both directions: front to back and back to front.

For flashcards containing definitions of terms, put the term to be defined on the front of the card, and the definition (typically longer) on the back of the card. The front of the card will be used as a reference key to link to your practice records. If it changes then the link to your practice records for that card will be broken, effectively resetting your progress. (I could look into ways to fix this problem in future releases)

You can install language support to enable syntax highlighting of your Flashdown (.fd) files in Visual Studio Code. See instructions in this repo: https://github.com/SteveRidout/flashdown-language-support

The Flashdown practice record (.fdr) plain text file format

The .fdr file extension stands for Flashdown practice Record, and these files contain a chronological record of each practice session, with a list of card you have practiced along with the score representing how well you remembered the information (1 = didn't remember, 2 = just about remembered, 3 = remembered, 4 = remembered well). Here's an example:

# 2022-10-17 20:14

Godwin's law, b: 4
Linus's law, b: 4
Goodhart's law, f: 3

# 2022-10-17 20:16

Sunk Cost Fallacy (aka Escalation of Commitment), b: 4
Declinism, f: 4
Outgroup Homogeneity Bias, b: 4
Placebo Effect, f: 4

There are two types of lines (ignoring empty lines which are just for readability and have no other meaning):

• Lines starting with # contain the datetime when you started the practice session
• The following lines are formatted like this: <front of card>, <direction>: <score>, where a direction of f means that you are shown the front of the card and need to recall the back, and b is the reverse, meaning that you are shown the back of the card and need to recall the front.

The file format is SRS algorithm agnostic. Since it stores the entire historical record you could run any spaced repetition algorithm over it, as long as the algorithm takes for input a list of (time, score) pairs for each card.

Set up development environment

Basic setup

# Clone this repo
git clone https://github.com/SteveRidout/flashdown.git

# Change working directory
cd flashdown

# Run with ts-node
npx ts-node src/flashdown.ts

Advanced setup

Alternatively, you can use webpack to continually watch your source files and rebuild when any of them change, which results in faster incremental builds. To do this, run the following in one terminal tab:

# This will run webpack and rebuild upon changes to source files
npm run dev

In a second terminal tab, run the compiled version of the app:

node dist/flashdown.js

Optionally, in a third terminal tab, you can keep an eye on updates to the debugLog.txt file. This is used to output debugging info while the app is running, which is not convenient to do using console.log() because Flashdown regularly clears the contents of the terminal it runs in.

tail -f debugLog.txt

Why create an interactive terminal app in 2022?

• Keeps UI code complexity relatively low, allowing for faster development and a simpler code base
• For now I'm not aiming at a mass audience, but if it happens to appeal to any other hacker types that would be cool
• Flashcard apps are suited to keyboard only input
• I liked the idea of working within a different set of constraints (compared to web development)
• There's something about the CLI aesthetic which appeals in a retro way
• Terminal apps have the nice property of being easy to use across multiple devices out of the box via ssh

(That all said, I wouldn't rule out creating a web version of this later which could have a wider appeal)