The encoding of MAM for Sefaria

Author: Ben Denckla

Revision: 2026-10-26

Introduction

MAM (Miqra According to the Masorah) is a digital edition of the Hebrew Bible, based on the Aleppo Codex and related manuscripts, whose text is on Hebrew Wikisource. MAM-for-Sefaria is the extract of MAM that Sefaria imports and shows as its default Tanakh. This page describes the files that Sefaria imports, what they have, and how they encode it.

The files are in the folder csv/ of the MAM-for-Sefaria directory of the repository MAM-basics, whose README says how current they are. Every example of MAM-for-Sefaria on this page, and every count of what it has, is taken from those files.

This page has three typographic conventions:

  1. Text styled like this reveals more on hover, where the medium allows hovering.
  2. Text styled like this draws attention to letters of a form, as to the ב of אבג.
  3. ZARQA is the name of a Unicode code point, less the words that name its script and class. Hovering shows the whole name, here HEBREW ACCENT ZARQA.

The files

The folder csv/ has a file for each of the 39 books, named by the book's title on Sefaria, as I Samuel.csv is, and a provenance note, _provenance.md. Each book's file is a CSV file in UTF-8, with CRLF line ends and no byte-order mark. Its first five rows are a header, each row a key and its value. Every file has the same values, but for the first:

Key Value
Index Title the book's title on Sefaria
Version Title Miqra according to the Masorah
Language he
Version Source https://he.wikisource.org/wiki/%D7%9E%D7%A7%D7%A8%D7%90_%D7%A2%D7%9C_%D7%A4%D7%99_%D7%94%D7%9E%D7%A1%D7%95%D7%A8%D7%94
Version Notes the paragraph of HTML below

The value of Version Notes, rendered, is:

Miqra According to the Masorah (MAM) is a digital Hebrew edition of the Tanakh based on the Aleppo Codex and related manuscripts. It is designed for readers, and as such it contains added elements to aid vocalization of the text. For instance: When an accent is marked in an unstressed syllable, an extra accent is added in the proper place (pashta, zarqa, segol, telisha). Legarmeih and paseq are visibly distinguished. Qamaz qatan is indicated by its designated Unicode character (alternatives are documented where traditions differ about its application).
The text of MAM is fully documented. The complete introduction to the edition (Hebrew) explains the types of editorial decisions that have been made and the reasons for them (English abstract). In addition, every word in the Bible about which there is some textual concern or ambiguity includes a documentation note; these notes can be viewed conveniently here. If an error is discovered, it may be reported to User:Dovi at Hebrew Wikisource. Please check the documentation notes before reporting an error.

After the header, each of the 23,206 rows is a verse, with two fields: the verse's reference, such as Genesis 1:1, and the verse's text, in HTML.

The folder misc/unicode-names/ has a listing for each book's file, which names each code point of each verse's text. The page The Unicode-name listings of MAM for Sefaria describes the listings, and gives the name and count of each of the 92 code points that the files have.

Verse numbering

The verses are numbered as Sefaria numbers them. The page Versification Differences: MAM, BHS, and Sefaria lists where that numbering differs from MAM's and BHS's.

Sefaria's numbering has Josh 21:36–37, for which MAM has no text. Each of these rows has only an EM DASH (—), since an empty field would let the text of another version show at that verse on Sefaria. The files have no other EM DASH.

Markup

The verse text of csv/ is HTML with 6 elements, of which only span has an attribute, its class. These are all the elements and classes that the files have:

Element Class Count What it holds
span mam-spi-samekh 1,982 a samekh break, {ס}
span mam-spi-pe 1,571 a pe break, {פ}
span mam-spi-invnun 9 an inverted nun, NUN HAFUKHA
span mam-implicit-maqaf 116 a gray maqaf (see Gray maqaf)
span mam-kq 1,047 a ketiv and its qere
span mam-kq-k 1,055 a ketiv, in parentheses
span mam-kq-q 1,056 a qere, in square brackets
span mam-kq-trivial 149 a trivial ketiv/qere pair, as one pointed atom
span k-velo-q-maq 2 a maqaf after a ketiv velo qere
b 1,787 the PASEQ of a legarmeh
small 531 the PASEQ of a paseq (508), or a small letter (23)
big 27 a large letter
sup 4 a hung letter
br 1,571 nothing: it follows each pe break

Legarmeh and paseq

A legarmeh and a paseq are both the code point PASEQ. The files tell them apart by markup and spacing:

Example Reference Mark Encoding Count
וְכֹ֣ל ׀ שִׂ֣יחַ Gen 2:5 legarmeh THIN SPACE, then PASEQ in <b>, then the space before the next atom 1,787
אֱלֹהִ֤ים ׀ לָאוֹר֙ Gen 1:5 paseq THIN SPACE, PASEQ in <small>, THIN SPACE; no other space comes before the next atom 508

So the spacing keeps a legarmeh with the atom before it, and puts a paseq between two atoms.

Spaces

The files write NO-BREAK SPACE and THIN SPACE as the character references &nbsp; (22,042 times) and &thinsp; (2,803 times), and have no other character reference. Each THIN SPACE is beside the PASEQ of a legarmeh or a paseq, as above. A NO-BREAK SPACE comes alone or in a run of eight:

Where Run Count
before a samekh or pe break one 3,553
after a samekh break eight 1,982
after an inverted nun one 8
before an inverted nun one 1
a space of song spacing eight 328

Song spacing, MAM-simple's shirah-space, is in these chapters, with these numbers of spaces:

Breaks and inverted nun

Each of the 1,982 samekh breaks is {ס} in a span of class mam-spi-samekh, with a NO-BREAK SPACE before it and eight after it, and each of the 1,571 pe breaks is {פ} in a span of class mam-spi-pe, with a NO-BREAK SPACE before it and a <br> after it. Most end a verse, but 145 samekh and 24 pe breaks are inside one.

Each of the 9 inverted nun marks is ׆ (NUN HAFUKHA) in a span of class mam-spi-invnun, at Num 10:35–36, and Ps 107:23–28 and 40.

Small, large and hung letters

A small letter is in <small> (23 times), a large letter in <big> (27 times) and a hung letter in <sup> (4 times, at Judg 18:30; Ps 80:14; and Job 38:13 and 15). Each of these elements holds one letter and its marks:

Example Reference What it has
בִּשְׁפַּרְפָּרָ֖א Dan 6:20 a small letter and a large one
רְשָׁעִ֣ים Job 38:13 a hung letter
(וגיש) [וְג֣וּשׁ] Job 7:5 a small letter in a ketiv

Ketiv and qere

Each of the 1,047 pairs of a ketiv and its qere is a span of class mam-kq, which holds the ketiv, unpointed and in parentheses, in a span of class mam-kq-k, and the qere, pointed and in square brackets, in a span of class mam-kq-q, with a separator between them: a space or, in 2 pairs, a MAQAF. The files keep the order that MAM's pages on Hebrew Wikisource have, which puts the qere first in 133 pairs, 130 of them right after a maqaf. By order, separator, and the words of each part, the pairs are of these shapes:

Example Reference q first? Separator Words Count
(הוצא) [הַיְצֵ֣א] Gen 8:17 a space 1, 1 887
אֶת־[יְע֥וּשׁ] (יעיש) Gen 36:5 q first a space 1, 1 131
(כי טוב) [כְּט֣וֹב] Judg 16:25 a space 2, 1 11
(בגד) [בָּ֣א גָ֑ד] Gen 30:11 a space 1, 2 8
(הייתה מוציא) [הָיִ֛יתָ הַמּוֹצִ֥יא] 2 Sam 5:2 a space 2, 2 5
אֶת־[מֵימֵ֥י רַגְלֵיהֶ֖ם] (שניהם) 2 Kgs 18:27 q first a space 1, 2 2
עַד־(יעבור)־[יַעֲבׇר־]זָֽעַם׃ Isa 26:20 a MAQAF 1, 1 1
בֶן־(בנימן)־[בָּנִ֔י מִן־]בְּנֵי־פֶ֖רֶץ 1 Chr 9:4 a MAQAF 1, 2 1
(תלום שם הפלשתים) [תְּלָא֥וּם שָׁ֙מָּה֙ פְּלִשְׁתִּ֔ים] 2 Sam 21:12 a space 3, 3 1

A ketiv velo qere, a ketiv that is written but not read, is a span of class mam-kq-k with no pair around it, at 2 Sam 13:33 and 15:21; 2 Kgs 5:18; Jer 38:16, 39:12 and 51:3; Ezek 48:16; and Ruth 3:12. A qere velo ketiv, a qere that is read but not written, is likewise a span of class mam-kq-q, at Judg 20:13; 2 Sam 16:23 and 18:20; 2 Kgs 19:31 and 37; Jer 31:38 and 50:29; and Ruth 3:5 and 17. A trivial pair, which the guide to MAM-simple's JSON describes as a ketiv/qere “whose two forms differ in a way that needs no separate display”, is one pointed atom in a span of class mam-kq-trivial. An example of each, with its count:

Example Reference What it is Count
(אם) Ruth 3:12 a ketiv velo qere 8
[אֵלַ֔י] Ruth 3:17 a qere velo ketiv 9
כִּֽי־(אם)־אַמְנ֥וֹן 2 Sam 13:33 a maqaf after a ketiv velo qere 2
אׇֽהֳלֹה֙ Gen 13:3 a trivial pair 149

Characters

Code points that stand for more than one mark

Some code points stand for different marks in different places: by the system of accents of the verse, prose or poetic, or, for PASEQ, by its markup. As MAM-for-Sefaria uses them:

Code point Where Count Mark
ZARQA prose verses 180 the zarqa's stress helper
ZARQA poetic verses 198 tsinnorit
ZINOR prose verses 988 zarqa
ZINOR poetic verses 251 tsinnor
PASEQ in <b> 1,787 legarmeh
PASEQ in <small> 508 paseq

Marks with code points of their own

MAM-for-Sefaria has each of these marks as a code point of its own. The counts are of the marks and of the atoms that have them:

Example Reference Code point Mark Marks Atoms
וּבְכׇל־הָרֶ֖מֶשׂ Gen 1:26 QAMATS QATAN qamats qatan 7,434 7,421
עֲוֺנִ֖י Gen 4:13 HOLAM HASER FOR VAV ḥolam ḥaser on a vav that is a consonant 416 416
בַּעֲצַ֢ת Ps 1:1 ATNAH HAFUKH atnaḥ hafukh, as opposed to YERAH BEN YOMO 195 195

A letter with geresh or gershayim and telisha gedolah

In 5 atoms, a letter has a GERESH or a GERSHAYIM and then a TELISHA GEDOLA; in 2 of them two letters do. The letters' code points, in order:

Example Reference Code points
זֶ֞֠ה Gen 5:29 ZAYIN, SEGOL, GERSHAYIM, TELISHA GEDOLA
קִ֞֠רְב֞֠וּ Lev 10:4 QOF, HIRIQ, GERSHAYIM, TELISHA GEDOLA
BET, GERSHAYIM, TELISHA GEDOLA
שֻׁ֜֠בוּ 2 Kgs 17:13 SHIN, SHIN DOT, QUBUTS, GERESH, TELISHA GEDOLA
וּ֜֠לְאֵ֜֠לֶּה Ezek 48:10 VAV, DAGESH OR MAPIQ, GERESH, TELISHA GEDOLA
ALEF, TSERE, GERESH, TELISHA GEDOLA
זֹ֞֠את Zeph 2:15 ZAYIN, HOLAM, GERSHAYIM, TELISHA GEDOLA

The zarqa and its stress helper

Each of the 1,239 ZINOR marks is on the last letter of its atom: the zarqa in prose verses and the tsinnor in poetic verses. Of them, 59 are on a lamed, as at Lev 4:2 below. In prose verses, each of the 180 ZARQA marks is the zarqa's stress helper, on an earlier letter of the atom than its ZINOR, as at Gen 19:4:

Example Reference Code points
טֶ֘רֶם֮ Gen 19:4 TET, SEGOL, ZARQA
RESH, SEGOL
FINAL MEM, ZINOR
יִשְׂרָאֵל֮ Lev 4:2 YOD, HIRIQ
SHIN, SIN DOT, SHEVA
RESH, QAMATS
ALEF, TSERE
LAMED, ZINOR

A meteg after the silluq

In 2 atoms, MAM's source identifies a silluq that has a meteg after it, on a later letter of the atom. MAM-for-Sefaria has the silluq and every other mark of each atom, but not that meteg, which other versions of MAM, MAM-simple among them, have:

Version 1 Kgs 7:37 Job 4:12
Sefaria לְכֻלָּֽהְנָה מֶֽנְהוּ
other versions of MAM לְכֻלָּֽהְנָֽה מֶֽנְהֽוּ

Mark order

The marks of each letter are in MAM's order, which is not Unicode's: a SHIN DOT or SIN DOT comes first, then a DAGESH OR MAPIQ, then a RAFE, and then the other marks, in the order MAM gives them. A note in MAM-basics says more. Unicode normalization puts the marks in Unicode's order, and would change the order of the marks of 143,042 of the 306,525 atoms of csv/.

What the files leave out

The handlers of py/mb_sefaria/mam4sef_handlers.py write nothing for these three things that MAM-simple has:

  1. Its notes on scroll differences (sdt-note). The files keep the text that each note is about, and have no notes. MAM's documentation notes, which MAM-simple does not have either, are in MAM-with-doc, to which the files' Version Notes link.
  2. The verse that four books repeat after their last (good-ending).
  3. The two strands of each verse that has two cantillations (cant-alef and cant-bet). The files keep the text that represents both strands at once (cant-combined).

Robust Unicode

Unicode normalization sorts the marks of each letter by their combining classes. A COMBINING GRAPHEME JOINER (CGJ) has combining class 0, so normalization moves no mark across one. MAM-for-Sefaria has 652 of them, each on a letter whose marks normalization would otherwise put in another order: it keeps the vowel or METEG after it in place after the marks before it. Every letter of the files that has two vowels has a CGJ between them. The tables give, for each kind, the code points of the letter in order.

Jerusalem

638 are in atoms spelled ירושלם (634) or ירושלמה (4), with or without a prefix, on the lamed. It has its own vowel, PATAH or QAMATS, then, in all but 1 of them, an accent or METEG, and after the CGJ an orphaned HIRIQ or SHEVA, the vowel of the yod that the spelling lacks:

Example Reference The lamed's code points Count
יְרוּשָׁלַ֖͏ִם Judg 1:7 LAMED, PATAH, TIPEHA, CGJ, HIRIQ 348 (1 with no accent or METEG)
יְרוּשָׁלָ֑͏ִם Josh 15:8 LAMED, QAMATS, ETNAHTA, CGJ, HIRIQ 286
יְרוּשָׁלַ֛͏ְמָה Isa 36:2 LAMED, PATAH, TEVIR, CGJ, SHEVA 3
יְרוּשָׁלָ֑͏ְמָה 2 Kgs 9:28 LAMED, QAMATS, ETNAHTA, CGJ, SHEVA 1

Two strands on one letter

The other 14 are in verses with two cantillations, on a letter whose text represents both strands: the marks before the CGJ are one strand's, and the marks after it are the other's. In 4 atoms, one strand has a QAMATS and an accent or METEG below the letter, and the other a PATAH and an accent above it:

Example References The letter's code points
עַל־פָּנָֽ͏ַ֗י׃ Exod 20:3 and Deut 5:7 NUN, QAMATS, METEG, CGJ, PATAH, REVIA
מִתָּ֑͏ַ֜חַת Exod 20:4 and Deut 5:8 TAV, DAGESH OR MAPIQ, QAMATS, ETNAHTA, CGJ, PATAH, GERESH

In 10 atoms, one strand has an accent below the letter, and the other a METEG:

Example References The letter's code points
יִשְׂרָאֵ֑͏ֽל׃ Gen 35:22 ALEF, TSERE, ETNAHTA, CGJ, METEG
עֲבָדִ֑͏ֽים׃ Exod 20:2 and Deut 5:6 DALET, HIRIQ, ETNAHTA, CGJ, METEG
לֹֽ֣א־יִהְיֶ֥͏ֽה־לְךָ֛֩ Exod 20:3 and Deut 5:7 YOD, SEGOL, MERKHA, CGJ, METEG
וּבִנְךָ֣͏ֽ־וּ֠בִתֶּ֗ךָ Exod 20:10 FINAL KAF, QAMATS, MUNAH, CGJ, METEG
תִּֿרְצָ֖͏ֽח׃ Exod 20:13 and Deut 5:17 TSADI, QAMATS, TIPEHA, CGJ, METEG
תִּֿנְאָ֑͏ֽף׃ Exod 20:13 and Deut 5:17 ALEF, QAMATS, ETNAHTA, CGJ, METEG