Sefaria Auto Linker

Lev Eliezer Israel edited this page Dec 20, 2016 · 7 revisions

Sefaria Auto-Linker

The Sefaria auto linker recognizes references on a web page, links them to the corresponding texts on Sefaria, and optionally provides a popup containing the text of the references.

It can be run either as a bookmarklet from a browser or embedded into page code. If run as a bookmarklet, a user can find references on any webpage the s/he visits by clicking the bookmarklet. If embedded into page code, it will find references every time any user loads the page.

Bookmarklet

You can get browser bookmarklets here

Embed Code

Place this code on your web page, just before the </body> tag.

    <script type="text/javascript" charset="utf-8" src="http://sefaria.org/linker.js"></script>
    <script>
        sefaria.link();
    </script>

Options for embed code

Options can be passed to the call to sefaria.link() that will change the behavior of the plugin

selector

The selector option is used to specify which elements should be checked for references. The value of selector is a string - a CSS selector. You can specify an #id a .class or any other CSS selector.

If it is not specified, all of the textual content within the <body> tag is checked for links.

mode

The mode option affects how the found references behave. If not specified, the default is "popup-hover" mode.

The value of mode is one of the following strings:

  • "popup-hover" - when the user's mouse hovers over a reference, a popup with the textual content is displayed. A click on the reference goes to the content in Sefaria.

  • "popup-click" - when the the user clicks on a reference, a popup is displayed with the textual content. Within the popup is a link to Sefaria.

  • "link" - The references are turned into links, which open in a new browser tab when clicked. There is no popup with textual content.

popupStyles

The popupStyles option allows for custom styling of the popup box - colors, borders, fonts, etc. If present, it must be a dictionary of JavaScript style attributes and their values. See examples below.

Examples of calling the plugin with options

Only look for references in paragraphs with a "Torah" class.

    sefaria.link({selector: ".Torah"});

Invoke plugin in click-to-popup mode

    sefaria.link({mode: "popup-click"});

Add some custom styling to the popup box

    sefaria.link({
        popupStyles: {
            color: "#e3fc11",
            border: '4em solid black' 
        }
    });

Do all of the above, together

    sefaria.link({
        mode: "popup-click",
        selector: ".Torah",
        popupStyles: {
            color: "#e3fc11",
                    border: '4em solid black' 
        }
    });

Citation Format

We've worked pretty hard to help the linker capture as many references as possible. In general, if the title is written out in full, followed by the numeric references, it will work well. Every text on Sefaria can be referenced, but some of them are trickier than others.

Going into a bit more detail:

  • Punctuation shouldn't be an issue - space, comma, period, and colon in a reference will all be fine.

  • Dash has special meaning - it indicates a range (see the examples, below.) Any extra dash will trip us up.

  • For each text, we recognize a number of common spelling variants. For example, for "2 Kings", we'll recognize the titles: Melachim Bet, Melachim II, Second Kings, 2 Kings, II Melachim, Kings II, II Melakhim, and II Kings. For each work, the text table of contents on Sefaria will list the recognized titles, at the bottom of the page - e.g. http://www.sefaria.org/II_Kings

  • We'll recognize chapter level and verse level references, as well as ranges, so all of these are valid:

    • Second Kings 2
    • II Kings, 2:5
    • II Kings 2 5
    • Kings II 2-4
    • 2 Kings 2:3-6
    • Melachim II 2:3-3:3
  • Some texts use Talmudic numbering (not just the Talmud), for those, we expect the references in that form. For example:

    • Shabbat 7b
    • Zohar 2, 20b (That means volume 2, page 20b)
    • Rif Shabbat 7b (Refers to 7b in 'dapei ha Rif')

Where we will fail to capture the reference is when the title is interwoven in the text. For example: Mishnah Taanit 4:3 would work well, but In the 3rd Mishnah of Taanit, chapter 4 would fail to match. The general rule is - cite completely, and don't mix anything into the citation. That will work well for most of the core canon - Tanach, Mishnah, Tosefta, Talmud, Midrash, Zohar, etc.

Where it gets trickier is with texts that have a complex structure. For example, to cite the Four Questions in the Haggadah, this citation would work: Haggadah, Magid, Four Questions, as would a number of variants. Still - it's unlikely that a citation like that will occur on its own. The Mishneh Torah is a similar situation - we record many variants of section names of the Mishneh Torah, but citations are hard to get right without looking at exactly how its recorded in our system. A foolproof way of always getting a good reference is to navigate to the text on Sefaria, select the text, and copy the citation from the URL.