Major reworking of the documentation

.github/workflows/release.yml

@@ -37,7 +37,7 @@ jobs:
               id: extract-release-notes
               uses: ffurrer2/extract-release-notes@v1
               with:
-                  changelog_file: docs/changelog.md
+                  changelog_file: docs/docs/changelog.md
 
             - name: Create Release
               id: create-release

.gitignore

@@ -29,6 +29,10 @@ tests/e2e/vault/
 site/
 venv/
 .venv/
+docs/docs/en/media/~*
+.obsidian/plugins/obsidian-spaced-repetition-beta/*
 
 # env
 env.sh
+
+

.prettierignore

@@ -6,3 +6,4 @@ node_modules
 .pnp.loader.mjs
 pnpm-lock.yaml
 tests/e2e/vault/
+docs

docs/docs/en/algorithms.md

@@ -0,0 +1,64 @@
+# Learning Algorithms
+
+A learning algorithm is a formula that determines when a note or flashcard should next be reviewed.
+
+Algorithm | Status
+- | -
+[SM-2-OSR](#sm-2-osr) | Implemented
+[FSRS](#fsrs) | Planned
+[User Defined Intervals](#user-specified-intervals) | Planned
+
+## SM-2-OSR
+
+-   The `SM-2-OSR` algorithm is a variant of [Anki's algorithm](https://faqs.ankiweb.net/what-spaced-repetition-algorithm.html) which is based on the [SM-2 algorithm](https://www.supermemo.com/en/archives1990-2015/english/ol/sm2).
+-   It supports ternary reviews i.e. a concept is either hard, good, or easy at the time of review.
+-   initial ease is weighted (using max_link_factor) depending on the average ease of linked notes, note importance, and the base ease.
+-   Anki also applies a small amount of random “fuzz” to prevent cards that were introduced at the same time and given the same ratings from sticking together and always coming up for review on the same day."
+-    The algorithm is essentially the same for both notes and flashcards - apart from the PageRanks
+
+### Algorithm Details
+
+!!! warning
+
+    Note that this hasn't been updated in a while,
+    please see the [code](https://github.com/st3v3nmw/obsidian-spaced-repetition/blob/master/src/scheduling.ts).
+
+-   `if link_count > 0: initial_ease = (1 - link_contribution) * base_ease + link_contribution * average_ease`
+        -   `link_contribution = max_link_factor * min(1.0, log(link_count + 0.5) / log(64))` (cater for uncertainty)
+    -   The importance of the different concepts/notes is determined using the PageRank algorithm (not all notes are created equal xD)
+        -   On most occasions, the most fundamental concepts/notes have higher importance
+-   If the user reviews a concept/note as:
+    -   easy, the ease increases by `20` and the interval changes to `old_interval * new_ease / 100 * 1.3` (the 1.3 is the easy bonus)
+    -   good, the ease remains unchanged and the interval changes to `old_interval * old_ease / 100`
+    -   hard, the ease decreases by `20` and the interval changes to `old_interval * 0.5`
+        -   The `0.5` can be modified in settings
+        -   `minimum ease = 130`
+    -   For `8` or more days:
+        -   `interval += random_choice({-fuzz, 0, +fuzz})`
+            -   where `fuzz = ceil(0.05 * interval)`
+            -   [Anki docs](https://faqs.ankiweb.net/what-spaced-repetition-algorithm.html):
+                > "[...] Anki also applies a small amount of random “fuzz” to prevent cards that were introduced at the same time and given the same ratings from sticking together and always coming up for review on the same day."
+-   The scheduling information is stored in the YAML front matter
+
+---
+
+
+## FSRS
+
+The algorithm is detailed at:
+[fsrs4anki](https://github.com/open-spaced-repetition/fsrs4anki/wiki)
+
+Incorporation of the FSRS algorithm into this plugin has not yet occurred. For progress see:
+[ [FEAT] sm-2 is outdated, can you please replace it with the fsrs algorithm? #748 ](https://github.com/st3v3nmw/obsidian-spaced-repetition/issues/748)
+
+---
+
+
+## User Specified Intervals
+
+This is the simplest "algorithm" possible. There are fixed intervals configured by the user for each of the possible review outcomes.
+
+For example, `hard` might be configured for an interval of 1 day.
+
+Implementation of this technique has not yet occurred. For progress see:
+[ [FEAT] user defined "Easy, Good, Hard" values instead of or in addition to the algorithm defined one. #741 ](https://github.com/st3v3nmw/obsidian-spaced-repetition/issues/741)

docs/en/contributing.md → docs/docs/en/contributing.md

@@ -10,6 +10,21 @@ First off, thanks for wanting to contribute to the Spaced Repetition plugin!
 
 ## Translating
 
+The plugin has been translated into the following languages by the Obsidian community 😄.
+
+- Arabic / العربية
+- Chinese (Simplified) / 简体中文
+- Chinese (Traditional) / 繁體中文
+- Czech / čeština
+- German / Deutsch
+- Italian / Italiano
+- Korean / 한국어
+- Japanese / 日本語
+- Polish / Polski
+- Portuguese (Brazil) / Português do Brasil
+- Spanish / Español
+- Russian / русский
+
 ### Steps
 
 To help translate the plugin to your language:
@@ -56,6 +71,9 @@ Please note that:
 1. Only the strings(templates) on the right of the key should be translated.
 2. Text inside `${}` isn't translated. This is used to replace variables in code. For instance, if interval = 4, it becomes `4 days` in English & `Siku 4` in Swahili. Quite nifty if you ask me.
 
+---
+
+
 ## Code
 
 1. Make your changes.
@@ -77,7 +95,7 @@ Please note that:
 5. If your "business logic" is properly decoupled from Obsidian APIs, write some unit tests.
     - This project uses [jest](https://jestjs.io/), tests are stored in `tests/`.
     - `pnpm test`
-6. Add your change to the `[Unreleased]` section of the changelog (`docs/changelog.md`).
+6. Add your change to the `[Unreleased]` section of the changelog (`docs/docs/changelog.md`).
     - The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), TL;DR:
         - `Added` for new features.
         - `Changed` for changes in existing functionality.
@@ -91,6 +109,9 @@ Please note that:
     - Format the code in case any warnings are raised: `pnpm format`
 8. Open the pull request.
 
+---
+
+
 ## Documentation
 
 The documentation consists of Markdown files which [MkDocs](https://www.mkdocs.org/) converts to static web pages.
@@ -126,6 +147,9 @@ For larger diffs, it's important that you check how your docs look like as expla
 3. Copy the files from the English (`en`) folder into the new folder.
 4. Translate then open a pull request.
 
+---
+
+
 ## Maintenance
 
 ### Releases

docs/docs/en/data-storage.md

@@ -0,0 +1,63 @@
+# Data Storage
+
+## Scheduling Information
+
+### Individual Markdown Files
+
+This is the original method used for storing the scheduling information for cards and notes.
+
+For cards this is stored in an HTML comment for that card. For example with the card:
+```
+The RCU and WCU limits for a single partition key value::3000 RCU, 1000 WCU
+```
+
+When the card is reviewed, an HTML comment will be added after the card's text, such as:
+```
+<!--SR:!2024-08-16,51,230-->
+```
+
+By default, the comment is stored on the line following the card text.
+Alternatively, it can be stored on the same line by enabling the 
+[Save scheduling comment on the same line as the flashcard's last line?](user-options.md#storage-of-scheduling-data) option.
+
+Scheduling information for the note is kept at the beginning of the file, in YAML format within the frontmatter section.
+For example:
+
+![note-frontmatter](https://github.com/user-attachments/assets/b9744f50-c897-46ad-ab34-1bbc55796b57)
+
+!!! note "Raw text format"
+        ---
+        sr-due: 2024-07-01
+        sr-interval: 3
+        sr-ease: 269
+        ---
+
+### Single Scheduling File
+
+The scheduling information for all cards and notes is kept in a single dedicated file.
+
+Implementation of this has not yet occurred. For progress see:
+
+[[FEAT] Stop using YAML; Move plugin info and data to separate file #162](https://github.com/st3v3nmw/obsidian-spaced-repetition/issues/162)
+
+---
+
+## User Options
+
+All user [options](user-options.md) are stored in `data.json` in the plugin folder.
+
+---
+
+
+
+## Card Postponement List
+
+This records a list of cards reviewed today that have sibling cards that shouldn't be reviewed until tomorrow.
+
+Cards are only added to this list if the [Bury sibling cards until the next day](user-options.md#flashcard-review) setting is turned on.
+
+This information is also kept in the `data.json` file.
+
+!!! note
+
+    To minimise the space required for this, a copy of the card is not stored. Rather a small numeric hash code ("fingerprint") is kept.

docs/docs/en/flashcards/basic-cloze-cards.md

@@ -0,0 +1,110 @@
+# Basic Cloze Cards
+
+With [Single & Multiline Cards](../flashcards/qanda-cards.md) the text of both the front and back of each card is specified.
+
+With `cloze` cards a single text is specified, together with an identification of which parts of the text should be obscured.
+
+The front of the card is displayed as the text with (one or more) `cloze deletions` obscured.
+
+## Cloze Deletions
+
+A part of the card text is identified as a cloze deletion by surrounding it with the `cloze delimiter`.
+
+### Single Cloze Deletion
+By default, the cloze delimiter is `==`, and a simple cloze card would be:
+```
+The first female prime minister of Australia was ==Julia Gillard==
+```
+
+!!! note "Displayed when reviewed"
+    <div class="grid" markdown>
+
+    !!! tip "Initial View"
+
+        The first female prime minister of Australia was [...]
+
+    !!! tip "After `Show Answer` Clicked"
+
+        The first female prime minister of Australia was Julia Gillard
+
+    </div>
+
+
+
+### Multiple Cloze Deletions
+If the card text identifies multiple parts as cloze deletions, then multiple cards will be shown for review, each one occluding one deletion, while leaving the other deletions visible.
+
+For instance, the following note:
+```
+The first female ==prime minister== of Australia was ==Julia Gillard==
+```
+
+!!! note ""
+    <div class="grid" markdown>
+
+    !!! tip "Card 1 Initial View"
+
+        The first female [...] of Australia was Julia Gillard
+
+    !!! tip "Card 2 Initial View"
+
+        The first female prime minister of Australia was [...]
+
+    </div>
+
+!!! tip "After `Show Answer` Clicked (same for both cards)"
+
+    The first female prime minister of Australia was Julia Gillard
+
+These two cards are considered sibling cards. See [sibling cards](flashcards-overview.md#sibling-cards) regarding the 
+[Bury sibling cards until the next day](../user-options.md#flashcard-review) scheduling option.
+
+## Cloze Delimiter
+
+The cloze delimiter can be modified in [settings](../user-options.md#flashcard-review), e.g. to `**`, or curly braces `{{text in curly braces}}`.
+
+
+<!-- 
+## Cloze Hints
+
+Hints can be included for any of the cloze deletions, using the `^[text of hint]` syntax. For example:
+
+```
+Kaleida, funded to the tune of ==$40 million==^[USD]
+by Apple Computer and IBM in ==1991==^[year]
+```
+
+!!! note "Front of card 1"
+    Kaleida, funded to the tune of [USD] by Apple Computer and IBM in 1991
+!!! note "Front of card 2"
+    Kaleida, funded to the tune of $40 million by Apple Computer and IBM in [year]
+
+
+## Deletion Groups
+
+In the above examples, each card shown for review has one cloze deletion shown and all the others obscured.
+
+`Deletion groups` allow this to be tailored by specifying a `group number` for each cloze deletion.
+
+For example:
+```
+This is ==in group 1==[^1], this ==in group 2==[^2] 
+and this also ==in group 1==[^1]
+```
+
+!!! note "Front of card 1"
+    This is  [...], this in group 2 and this also [...]
+!!! note "Front of card 2"
+    This is in group 1, this  [...] and this also in group 1
+!!! note "Back of both cards"
+    This is in group 1, this in group 2 and this also in group 1
+
+!!! warning
+    When using deletion groups, every cloze deletion must include the group number
+ -->
+
+## Anki style
+
+!!! warning
+    Anki style `{{c1:This text}} would {{c2:generate}} {{c1:2 cards}}` cloze deletions are not currently supported. This feature is being tracked [here](https://github.com/st3v3nmw/obsidian-spaced-repetition/issues/93/).
+