losrs

losrs lets you create Spaced Repetition System (SRS) cards in markdown format and review them from your terminal.

Installation

losrs works on Linux, macOS, and (maybe) Windows and can be installed in different ways:

The recommended way to install losrs is to download the latest pre-built version for your system¹ from the releases page.

Alternatively, build from source by downloading rust and running:

cargo build --release; cp target/release/losrs $YOUR_BIN_DIR

Getting started

Create a "project" directory and a "pages" directory within it to store the card files (see History):

mkdir -p my-cards/pages ; cd my-cards; git init .

Create a markdown file inside the pages directory with a top level unordered list, and at least one list item that ends with #card, for example:

- What is the format for a losrs card prompt? #card
  - Unordered list item with `#card` in the end
- What is the format for a losrs card response? #card
  - Unordered sublist for an unordered list item with `#card` in the end

You can now review the cards either in a specific page file via losrs review pages/my-first-page.md or the whole project via losrs review .

Once you are done reviewing, don't forget to check in your changes!

git add .; git diff --staged; git commit -m 'Reviewed cards'; git push

Cards with images

Create an "assets" directory within your cards "project directory"

cd my-cards; mkdir assets

Copy the image you would like to use to the assets directory

cp .../symmetric-lens.png assets/

Create a card that refers to the image from "project directory"

- How does a symmetric lens look (visualize)? #card
  - ![](assets/symmetric-lens.png){height=50%}

Ensure image rendering prerequisites are satisfied, then use losrs show to confirm the image renders as expected.

Image rendering prerequisites

To render images in your cards you can use losrs with output.format = "(sixel|kitty|i-term)", see losrs config --help.

All image based formats require:

• Pandoc available on the $PATH
• Typst available on the $PATH

Each image protocol requires your terminal to support it. To see which terminals support sixel visit Are We Sixel Yet?.

For sixel you will need img2sixel (via libsixel) available on the $PATH. There is an outstanding TODO to not require img2sixel.

Rendering pipeline is basically:

markdown -> typst -> png -> image-protocol

And was inspired by presenterm. The reasons presenterm has for converting LaTeX to Typst do not apply to this project, but I found it easy to work with this pipeline so I'm keeping it. It would be nice to remove the dependency on Typst and to support more LaTeX, but I am unlikely to get around to changing this any time soon.

Limitations

Things that are known to NOT work:

• Rendering references
• Rendering LaTeX code that pandoc does not recognise. See pandoc's source for a list of symbols that are recognized by pandoc.
• If multiple cards with the same prompt are on the same page, when reviewing any of the cards the metadata will be updated for one of the cards, but not necessarily the one that was due for review. This is a consequence of not tracking the position of cards in the page, and updating code matching on prompt (this can probably be fixed now with CSN matching, but requires more thought).
• When rendering via an image based format, a card must fit in the terminal window by height. Specify a relative height like {height=50%} to ensure images fit.

History

This project was created as a workaround for Logseq SRS Algorithm being faulty and the fault only being fixed in the database version of Logseq to the exclusion of plain file version of Logseq.

The Logseq markdown card metadata format is still supported via the inline storage.metadata_mode, but that mode is deprecated and slated for removal², as using it is a bit rough due to an additional node property field that does not get hidden by Logseq.

losrs works with a very narrow subset of Logseq features, at the very least you need to ensure that Logseq graph root where you plan to use losrs is configured with :export/bullet-indentation :two-spaces .

Logseq directory layout

losrs borrows the "project" directory layout from Logseq, which is roughly as follows:

graph_root
├── assets
│   ├── image_1666695381725_0.png
│   ├── ...
└── pages
    ├── Sphere.md
    ├── ...

Footnotes

1. if you would like a new system to be added to releases, please file an issue. ↩

2. If you care about keeping this mode, please file an issue. ↩