Handling Commentaries

Brett Lockspeiser edited this page Dec 4, 2015 · 6 revisions


Sefaria's original design gives special structure to commentary texts which offers some benefits (automatic linking to basetexts, ability to generate new Index records on the fly) but requires a special structure which can be limiting. In cases where we have commentary texts that don't match these limitations, we begun using second method of creating commentary texts which is called in the code Commentary2. We intend to deprecate the original commentary structure and add features to general Index records to compensate, but for the time being we support both.

Original Style Commentaries

Original style commentaries on Sefaria function by having a storing a single Index record for each commentator. These commentator Index records can combine with any other Index record of a text, to create a virtual Index record for a commentary text.

For example, if we have a commentator record for Rashi and a text Index record for Shabbat, then Sefaria will understand Rashi on Shabbat to be a commentary on Shabbat. The structure of Rashi on Shabbat will be identical to the structure of the Shabbat with one addition level of depth in the terminal nodes called Comment. This allows for e.g., multiple distinct comments to be stored for a single segment of base text.

No index record is actually stored in the database for Rashi on Shabbat -- they are generated in code on the fly. This means, that there is no enforcing which commentaries actually exist, Rashi on Zohar will be accepted as well as Rashi on Genesis.


When text is saved from a virtual commentary index, links are created automatically to its base text. The links are created by matching the structure of commentary text to its base. Hence when posting commentaries, each comment needs to be slotted in to the appropriate location according to its base text. If there is a segment or section for which the commentary does not say anything, these sections need to be left blank in the commentary text.


Because they impose restrictions on the structure of a commentary text, some commentaries don't fit in to Sefaria's original design. In order to allow commentaries of different structures to still appear to users of the site as commentaries (rather than being displayed in different category), the category "Commentary2" can be used to make any text appear like a commentary. These texts are functionally the same as ay other text in Sefaria (they can be simple or complex), but the special top level category Commentary2 allows them to appear like other commentaries. Commentary2 texts do not have autolinking.


  • The categories field should include 3 items (1) "Commentary2", (2) the top level category of the base text and (3) the name of the commentator. E.g., ["Commentary2", "Mishnah", "Rambam"].
  • Because the categories field is stored only in the English, the commentaor name must have a translation available in the hebrew_terms function of hebrew.py.
  • Commentary2 texts with titles that follow the form "Commentator on Book", will be ordered in the table of contents according to the order of the base book.
  • Commentary2 texts with titles of different forms are allowed (e.g., "Rambam's Introduction to the Mishnah"). In order to order these texts among others in the table of contents, they require an explicit order field on the index record. This fields needs to be a an array containing a single number (integer or float) which will position it between other records are desired. Examining the table of contents api will show other existing order numbers to be slotted between. Although some books have multiple number in their order field, only the first is examined in order the TOC, hence only one number is needed here.