From b15a4163d8354feaafe6529c6a344e2b5f614f82 Mon Sep 17 00:00:00 2001
From: "Jakob L. Kreuze" <zerodaysfordays@sdf.org>
Date: Sun, 26 Oct 2025 16:57:18 -0400
Subject: Add custom card types

---
 README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index f2c843c..043d1c7 100644
--- a/README.md
+++ b/README.md
@@ -39,3 +39,42 @@ Keys generated and modified by SRS Anywhere are prefixed by the `_` character.
   }
 ]
 ```
+
+### Custom Cards
+
+Custom card types can be defined in a `srs-anywhere-custom-card-types.js` file.
+To register a new card type, add it as a new entry to the `CARD_TYPES` object, where the key is the the name of the card type.
+A card type should be an object containing at least the following keys: `validate`, `front`, and `back`.
+`validate` takes the card and throws an `Error` if it is malformed.
+`front` returns the desired HTML code for the front of the card.
+`back` returns the desired HTML code for the back of the card.
+Optionally, `showFront` and `showBack` are functions that are evaluted when the front or back of the card are shown, respectively.
+
+For example, to define a card type for a [cloze deletion test](https://en.wikipedia.org/wiki/Cloze_test):
+
+```javascript
+const CLOZE_REGEX = /\[.*?\]/ig;
+CARD_TYPES["clozeAll"] = {
+  "validate": function (card) {
+    if (typeof card.back !== "string") {
+      throw new Error(`malformed card ${card.id}: invalid back (should be string)`)
+    }
+    if (!CLOZE_REGEX.test(card.back)) {
+      throw new Error(`malformed card ${card.id}: contains no cloze;
+please enclose deletion in brackets (e.g., [...])`)
+    }
+  },
+  "front": (card) => card.back.replaceAll(CLOZE_REGEX, '[...]'),
+  "back": (card) => card.back
+};
+```
+
+The `type` key in the cards JSON file associates an entry with the custom card type.
+
+```javascript
+{
+  "id": "cca013c4-450a-41a1-abed-28abdc73413a",
+  "type": "clozeAll",
+  "back": "This is a card containing a [cloze deletion]!"
+}
+```
-- 
cgit v1.3